Skip to main content

​
Overview

Moda tracks your Claude Agent SDK sessions, including Claude Code and custom agents built with claude-agent-sdk. Token usage, tool calls, agent turns, and session metadata are all captured automatically.

​
Why a Separate Package?

The Claude Agent SDK spawns Claude as a subprocess rather than making direct Anthropic API calls. This means standard Anthropic API instrumentation (moda-anthropic) does not fire. The moda-claude-agent-sdk package provides a dedicated instrumentor that wraps ClaudeSDKClient to capture agent-level spans.

​
Setup

pip install moda-ai moda-claude-agent-sdk claude-agent-sdk
The Claude Agent SDK is Python-only. Node.js is not currently supported.

​
Quick Start

import moda
import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

# Initialize Moda (automatically instruments claude-agent-sdk)
moda.init("YOUR_MODA_API_KEY")

# Set conversation and user context (recommended)
moda.conversation_id = "session_123"
moda.user_id = "user_456"

async def main():
    options = ClaudeAgentOptions(model="claude-sonnet-4-20250514")

    async with ClaudeSDKClient(options=options) as client:
        await client.query("What is the capital of France?")

        async for msg in client.receive_response():
            print(msg)

asyncio.run(main())

moda.flush()

​
Supported Features

FeatureCaptured
Agent sessionsYes
Streaming responsesYes
Tool use trackingYes (count of tool calls across turns)
Token usageYes (input, output, total, including cache tokens)
Model nameYes (request and response)
Session IDYes
Turn countYes

​
Data Captured

AttributeDescription
gen_ai.request.modelRequested model name
gen_ai.response.modelActual model used in response
gen_ai.usage.input_tokensInput token count (including cache tokens)
gen_ai.usage.output_tokensOutput token count
llm.usage.total_tokensTotal token count
claude_agent.num_turnsNumber of conversation turns
claude_agent.session_idAgent session identifier
claude_agent.tool_call_countTotal tool calls across all turns
moda.conversation_idConversation ID (when set)
moda.user_idUser ID (when set)

​
Troubleshooting

Data not appearing?
  • Make sure you installed moda-claude-agent-sdk separately — it is not included with moda-ai
  • Ensure moda.init() is called before creating the ClaudeSDKClient
  • Call moda.flush() before your program exits
Token counts missing?
  • Token usage comes from the ResultMessage at the end of the stream. Make sure you consume the full async generator from receive_response()
No spans generated?
  • Verify that claude-agent-sdk is installed and importable
  • Check that the instrumentor is active: moda.init() automatically enables it when the package is installed
For full SDK documentation, see the Python SDK guide.