Claude Agent SDK

The Claude Agent SDK is Anthropic’s framework for building agents on the same harness that powers Claude Code — tools, subagents, hooks, and skills, driven by the query() function or the ClaudeSDKClient class. Arize AX captures every Agent SDK run — agent invocations and the tool calls they make — via the openinference-instrumentation-claude-agent-sdk package.

Use this if you are building an application with the Claude Agents SDK. This page uses the OpenInference ClaudeAgentSDKInstrumentor to emit standard agent and tool spans into your application’s project — the right choice when the SDK is part of an app you’re instrumenting. If you instead want to trace Claude Code CLI (or SDK) sessions — the coding tool’s activity, tool usage, and token costs — via a plugin you enable through a settings file with no in-code instrumentor, use Claude Code instead.

Prerequisites

Python 3.10+
Node.js and the Claude Code CLI (npm install -g @anthropic-ai/claude-code), which the Agent SDK runs as a subprocess
An Arize AX account (sign up)
An ANTHROPIC_API_KEY from the Claude Console

Launch Arize AX

Sign in to your Arize AX account.
From Space Settings, copy your Space ID and API Key. You will set them as ARIZE_SPACE_ID and ARIZE_API_KEY below.

Install

pip install arize-otel \
  openinference-instrumentation-claude-agent-sdk \
  claude-agent-sdk

Configure credentials

export ARIZE_SPACE_ID="<your-space-id>"
export ARIZE_API_KEY="<your-api-key>"
export ARIZE_PROJECT_NAME="claude-agent-sdk-tracing-example"
export ANTHROPIC_API_KEY="<your-anthropic-api-key>"

Setup tracing

Instrument the Agent SDK with ClaudeAgentSDKInstrumentor. If your app serves the SDK from a web framework (FastAPI, Flask, etc.), do not rely on web-server instrumentation like FastAPIInstrumentor for agent observability — it records HTTP requests, not the SDK’s agent and tool spans. Add ClaudeAgentSDKInstrumentor alongside any transport instrumentation you keep.

# instrumentation.py
import os

from arize.otel import register
from openinference.instrumentation.claude_agent_sdk import (
    ClaudeAgentSDKInstrumentor,
)

tracer_provider = register(
    space_id=os.environ["ARIZE_SPACE_ID"],
    api_key=os.environ["ARIZE_API_KEY"],
    project_name=os.environ["ARIZE_PROJECT_NAME"],
)

ClaudeAgentSDKInstrumentor().instrument(tracer_provider=tracer_provider)
print("Arize AX tracing initialized for Claude Agent SDK.")

Run the Claude Agent SDK

The instrumentor traces both entry points:

query() — one AGENT span per call, for one-off tasks.
ClaudeSDKClient — one AGENT span per response turn (each receive_response() iteration), for multi-turn conversations that keep session context.

query()
ClaudeSDKClient

# example.py

# Importing instrumentation first ensures tracing is set up
# before the SDK is used.
from instrumentation import tracer_provider

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="What files are in this directory?",
        options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

# example_client.py

# Importing instrumentation first ensures tracing is set up
# before the SDK is used.
from instrumentation import tracer_provider

import asyncio

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions


async def main():
    options = ClaudeAgentOptions(allowed_tools=["Bash", "Glob"])
    async with ClaudeSDKClient(options=options) as client:
        await client.query("What files are in this directory?")
        async for message in client.receive_response():
            if hasattr(message, "result"):
                print(message.result)


asyncio.run(main())

Verify in Arize AX

Open your Arize AX space and select project claude-agent-sdk-tracing-example.
Within ~30 seconds you should see a new trace with an AGENT root span (ClaudeAgentSDK.query or ClaudeAgentSDK.ClaudeSDKClient.receive_response) carrying the prompt as input, the SDK result as output, and session.id, llm.model_name, and token-count metadata. Any tools the agent invokes appear as child TOOL spans with their inputs and outputs.
If no traces appear, see Troubleshooting.

Span coverage

The instrumentor emits AGENT spans (one per query() call or ClaudeSDKClient response turn) and child TOOL spans for each tool the agent invokes. It does not emit separate LLM spans: the Agent SDK runs the Claude Code binary as a subprocess and makes its model calls there, so an in-process instrumentor like AnthropicInstrumentor never sees them. Model, token-count, and cost detail is captured as attributes on the AGENT span (llm.model_name, llm.token_count.*, llm.cost.total).

Capture LLM spans

If you want per-generation LLM spans in addition to the AGENT span, synthesize them yourself from the AssistantMessage objects the SDK streams back — each one carries the model and its output. Start the LLM span while the assistant message streams (so it nests under the AGENT span) and set the token counts from the final ResultMessage, whose usage holds the accurate totals (the per-AssistantMessage usage is a partial, streaming value):

# example.py
from instrumentation import tracer_provider

import asyncio

from claude_agent_sdk import (
    query,
    ClaudeAgentOptions,
    AssistantMessage,
    ResultMessage,
    TextBlock,
)
from openinference.semconv.trace import SpanAttributes, OpenInferenceSpanKindValues

tracer = tracer_provider.get_tracer("claude-agent-sdk-llm-spans")


async def main():
    llm_spans = []
    async for message in query(
        prompt="Why is the ocean salty? Answer in one sentence.",
        options=ClaudeAgentOptions(max_turns=1),
    ):
        # Start an LLM span for each assistant turn (nests under the AGENT span).
        if isinstance(message, AssistantMessage):
            text = "".join(b.text for b in message.content if isinstance(b, TextBlock))
            span = tracer.start_span(f"{message.model} generation")
            span.set_attribute(
                SpanAttributes.OPENINFERENCE_SPAN_KIND,
                OpenInferenceSpanKindValues.LLM.value,
            )
            span.set_attribute(SpanAttributes.LLM_MODEL_NAME, message.model)
            span.set_attribute(SpanAttributes.LLM_PROVIDER, "anthropic")
            span.set_attribute(SpanAttributes.OUTPUT_VALUE, text)
            llm_spans.append(span)
        # Accurate token counts arrive only on the final result message.
        if isinstance(message, ResultMessage):
            usage = message.usage or {}
            if llm_spans and usage:
                last = llm_spans[-1]
                last.set_attribute(
                    SpanAttributes.LLM_TOKEN_COUNT_PROMPT, usage.get("input_tokens", 0)
                )
                last.set_attribute(
                    SpanAttributes.LLM_TOKEN_COUNT_COMPLETION,
                    usage.get("output_tokens", 0),
                )
            print(message.result)

    for span in llm_spans:
        span.end()


asyncio.run(main())

The LLM span nests under the AGENT span in the same trace. The token counts are exact for single-turn runs; for multi-turn runs they apply to the final turn.

Troubleshooting

No traces in Arize AX. Confirm ARIZE_SPACE_ID and ARIZE_API_KEY are set in the same shell that runs your script. Enable OpenTelemetry debug logs with export OTEL_LOG_LEVEL=debug and re-run.
Agent spans missing. ClaudeAgentSDKInstrumentor().instrument(...) must run before query() or ClaudeSDKClient is called. Make sure instrumentation.py is the first import in your entry point.
claude executable not found. The Agent SDK runs the Claude Code CLI as a subprocess. Install it with npm install -g @anthropic-ai/claude-code, or point the SDK at an existing binary with CLAUDE_CODE_EXECUTABLE.
401 from Anthropic. Verify ANTHROPIC_API_KEY is set and valid.
Tool spans expected but not present. TOOL spans only emit when the agent actually invokes a tool. Grant tools via ClaudeAgentOptions(allowed_tools=[...]) and give a prompt that requires them.

OpenTelemetry

LLM Providers

Agent Frameworks

Coding Agents

Platforms

Orchestration

Evaluation

Prerequisites

Launch Arize AX

Install

Configure credentials

Setup tracing

Run the Claude Agent SDK

Verify in Arize AX

Span coverage

Capture LLM spans

Troubleshooting

Resources

Claude Agent SDK Documentation

OpenInference Claude Agent SDK Instrumentor

Claude Agent SDK (Python) GitHub

​Prerequisites

​Launch Arize AX

​Install

​Configure credentials

​Setup tracing

​Run the Claude Agent SDK

​Verify in Arize AX

​Span coverage

​Capture LLM spans

​Troubleshooting

​Resources

Claude Agent SDK Documentation

OpenInference Claude Agent SDK Instrumentor

Claude Agent SDK (Python) GitHub

Prerequisites

Launch Arize AX

Install

Configure credentials

Setup tracing

Run the Claude Agent SDK

Verify in Arize AX

Span coverage

Capture LLM spans

Troubleshooting

Resources