> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Agent SDK

> Trace Claude Agent SDK query() and ClaudeSDKClient runs with OpenInference and send spans to Arize AX for LLM observability.

The [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview) 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`](https://github.com/Arize-ai/openinference/tree/main/python/instrumentation/openinference-instrumentation-claude-agent-sdk) package.

<Note>
  The Agent SDK runs the Claude Code binary as a subprocess, so it does not call the Anthropic API in-process. This instrumentor captures the SDK's agent and tool activity through the SDK's own hooks. To also capture detailed LLM spans, see [Capture LLM spans](#capture-llm-spans).
</Note>

<Note>
  **Use this if you are building an application with the Claude Agents SDK.** This page uses the OpenInference `ClaudeAgentSDKInstrumentor` to emit standard agent, tool, and LLM 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](/ax/integrations/platforms/claude-code/claude-code-tracing) instead.
</Note>

## Prerequisites

* Python 3.10+
* [Node.js](https://nodejs.org/) 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](https://arize.com/sign-up/))
* An `ANTHROPIC_API_KEY` from the [Claude Console](https://console.anthropic.com/)

## Launch Arize AX

1. Sign in to your [Arize AX account](https://app.arize.com/).
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

```bash theme={null}
pip install arize-otel \
  openinference-instrumentation-claude-agent-sdk \
  claude-agent-sdk
```

## Configure credentials

```bash theme={null}
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

<Note>
  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, tool, and LLM spans. Add `ClaudeAgentSDKInstrumentor` (and, for model-level detail, `AnthropicInstrumentor` — see [Capture LLM spans](#capture-llm-spans)) alongside any transport instrumentation you keep.
</Note>

```python theme={null}
# 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.

<Tabs>
  <Tab title="query()">
    ```python theme={null}
    # 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())
    ```
  </Tab>

  <Tab title="ClaudeSDKClient">
    ```python theme={null}
    # 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())
    ```
  </Tab>
</Tabs>

## 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](#troubleshooting).

## Capture LLM spans

The Agent SDK instrumentor emits AGENT and TOOL spans but not the underlying LLM generations. Add [`openinference-instrumentation-anthropic`](https://github.com/Arize-ai/openinference/tree/main/python/instrumentation/openinference-instrumentation-anthropic) alongside it to record model-level input, output, and token usage:

```bash theme={null}
pip install openinference-instrumentation-anthropic
```

```python theme={null}
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

<CardGroup>
  <Card icon="book-open" href="https://platform.claude.com/docs/en/agent-sdk/overview" title="Claude Agent SDK Documentation" horizontal />

  <Card icon="terminal" href="https://github.com/Arize-ai/openinference/tree/main/python/instrumentation/openinference-instrumentation-claude-agent-sdk" title="OpenInference Claude Agent SDK Instrumentor" horizontal />

  <Card icon="github" href="https://github.com/anthropics/claude-agent-sdk-python" title="Claude Agent SDK (Python) GitHub" horizontal />
</CardGroup>