Claude Agent SDK

​

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

1. Sign in to your Arize AX account.
2. 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

# 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

• 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.

# 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

1. Open your Arize AX space and select project claude-agent-sdk-tracing-example.
2. 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.
3. If no traces appear, see Troubleshooting.

​

Capture LLM spans

pip install openinference-instrumentation-anthropic

from openinference.instrumentation.anthropic import AnthropicInstrumentor

AnthropicInstrumentor().instrument(tracer_provider=tracer_provider)

​

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.

​

Resources