Installation

pip install observe-instrumentation-genai-claude-agent-sdk

If you don’t have a Claude Agent SDK application yet, try our examples which only need a valid Anthropic API key.

Check out the zero-code example for a quick start.

Usage

This section describes how to set up Claude Agent SDK instrumentation if you’re setting OpenTelemetry up manually. Check out the manual example for more details.

from observeinc.instrumentation.genai.claude_agent_sdk import ClaudeAgentSDKInstrumentor

# Instrument Claude Agent SDK
ClaudeAgentSDKInstrumentor().instrument()

# Use Claude Agent SDK as normal
import anyio
from claude_agent_sdk import ClaudeAgentOptions, AgentDefinition, AssistantMessage, TextBlock, query

async def main():
    options = ClaudeAgentOptions(
        agents={
            "assistant": AgentDefinition(
                description="A helpful assistant",
                prompt="You are a helpful assistant.",
                tools=["Read"],
                model="sonnet",
            ),
        },
        include_partial_messages=True,
    )

    async for message in query(
        prompt="Hello, Claude!",
        options=options,
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(block.text)

anyio.run(main)

Call instrument() before from claude_agent_sdk import query. The instrumentation replaces query on the claude_agent_sdk module, so a query imported earlier still points at the original function and its calls are not traced. Calls to claude_agent_sdk.query(...) and ClaudeSDKClient are traced regardless of import order. This only matters for manual setup: opentelemetry-instrument instruments before your code runs.

With ClaudeSDKClient, each turn of a connection gets its own invoke_agent span, however many receive_response() calls read it. The span opens under whatever span was active when you called query() for that turn. A turn that starts background work stays open until that work finishes or the next turn begins, so its span can include the time you spent before sending the next prompt.

Configuration

export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_AND_EVENT

ClaudeAgentSDKInstrumentor().instrument(agent_name="support-triage")

Token Usage

Each invoke_agent span reports only the tokens of its own agent’s calls. A subagent’s calls count on the subagent’s span, not on the span of the agent that delegated to it, so adding up the invoke_agent spans of a run counts each call once. Don’t also add the chat spans: they cover the same calls, so each call would be counted twice. With ClaudeSDKClient each turn gets its own root invoke_agent span; gen_ai.conversation.id groups the turns.

That sum falls short of what the run used in three cases, described below: a subagent’s output, calls the CLI makes for itself, and a turn that ends without a result, whose root span then reports no tokens.

Agent spans carry only the two totals, gen_ai.usage.input_tokens (cache reads and writes included) and gen_ai.usage.output_tokens. The cache and reasoning breakdowns are only on the chat spans, because the GenAI conventions define them for model calls, not for agent spans. To get them for a whole run, add them up from the chat spans.

• The root agent takes its counts from the usage field of each ResultMessage, which counts the root agent’s own calls since the previous result, not its subagents’. They are accurate whether or not stream events are on, and for resumed sessions too.

• A subagent gets no total of its own from the CLI, so its span adds up its chat spans. Input counts are accurate; output counts are not. The CLI forwards no stream events for a subagent, so each of its calls reports the near-zero output figure from when the call started. The subagent span and each of its chat spans carry claude_agent_sdk.usage.is_partial set to true.

Calls the CLI makes for itself, such as the one that gives a new session its title, are counted on no span. Only the session-wide ResultMessage.model_usage includes them.

A turn that ends without a result, because the stream failed or the run was closed part-way, leaves its root span without token counts. Its chat spans still carry theirs.

No span reports cost. ResultMessage.total_cost_usd covers the whole session and every agent in it, so it fits no single span. Read it in your own code if you need it.

References

• OpenTelemetry Project

• OpenTelemetry GenAI semantic conventions

• Claude Agent SDK (Python)

• Anthropic Documentation