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

# Claude Agent SDK

> Auto-instrument the Claude Agent SDK for agent and tool tracing

Automatically capture agent invocations, subagent delegations, tool calls, and token usage from the Claude Agent SDK (Claude Code as a library).

## Setup

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import traceroot
    from traceroot import Integration

    traceroot.initialize(integrations=[Integration.CLAUDE_AGENT_SDK])
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import * as claudeAgentSDK from '@anthropic-ai/claude-agent-sdk';
    import { TraceRoot } from '@traceroot-ai/traceroot';

    TraceRoot.initialize({
      instrumentModules: { claudeAgentSDK },
    });
    ```
  </Tab>
</Tabs>

## Usage

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

    # Define subagents
    researcher = AgentDefinition(
        description="Research specialist for gathering information.",
        prompt="You are a research specialist. Use WebSearch to find info.",
        tools=["WebSearch"],
        model="haiku",
    )

    # Run the agent with subagents
    async for message in query(
        prompt="Research the latest trends in AI observability",
        options=ClaudeAgentOptions(
            allowed_tools=["Agent", "Bash", "Read", "Glob", "Grep"],
            agents={"researcher": researcher},
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { query, AgentDefinition } from '@anthropic-ai/claude-agent-sdk';

    const researcher: AgentDefinition = {
      description: 'Research specialist for gathering information.',
      prompt: 'You are a research specialist. Use WebSearch to find info.',
      tools: ['WebSearch'],
      model: 'haiku',
    };

    async function main() {
      for await (const message of query({
        prompt: 'Research the latest trends in AI observability',
        options: {
          allowedTools: ['Agent', 'Bash', 'Read', 'Glob', 'Grep'],
          agents: { researcher },
        },
      })) {
        if ('result' in message) {
          console.log(message.result);
        }
      }
    }
    main().catch(console.error);
    ```
  </Tab>
</Tabs>

## What Gets Captured

| Attribute            | Description                                                |
| -------------------- | ---------------------------------------------------------- |
| Agent queries        | Each `query()` call as a top-level agent span              |
| Subagent invocations | Each subagent delegation via the Agent tool                |
| Tool calls           | Built-in tools (Read, Write, Bash, Glob, Grep, WebSearch)  |
| Token usage          | Aggregated input/output tokens per query                   |
| Cost                 | Total cost for the full query execution                    |
| Model name           | The model used (e.g., claude-sonnet-4-6, claude-haiku-4-5) |

## Run the example

Clone the repo and run a complete agent end-to-end.

<CardGroup cols={2}>
  <Card title="Python" icon="python" href="https://github.com/traceroot-ai/traceroot/tree/main/examples/python/claude-agent-sdk">
    Run the Python example
  </Card>

  <Card title="TypeScript" icon="js" href="https://github.com/traceroot-ai/traceroot/tree/main/examples/typescript/claude-agent-sdk">
    Run the TypeScript example
  </Card>
</CardGroup>