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

# Claude Agent SDK

> Using Moda with the Claude Agent SDK

## Overview

Moda tracks your Claude Agent SDK sessions, including Claude Code and custom agents built with `claude-agent-sdk`. Token usage, tool calls, agent turns, and session metadata are all captured automatically.

## Why a Separate Package?

The Claude Agent SDK spawns Claude as a subprocess rather than making direct Anthropic API calls. This means standard Anthropic API instrumentation (`moda-anthropic`) does not fire. The `moda-claude-agent-sdk` package provides a dedicated instrumentor that wraps `ClaudeSDKClient` to capture agent-level spans.

## Setup

```bash theme={"dark"}
pip install moda-ai moda-claude-agent-sdk claude-agent-sdk
```

<Note>
  The Claude Agent SDK is Python-only. Node.js is not currently supported.
</Note>

## Quick Start

```python theme={"dark"}
import moda
import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

# Initialize Moda (automatically instruments claude-agent-sdk)
moda.init("YOUR_MODA_API_KEY")

# Set conversation and user context (recommended)
moda.conversation_id = "session_123"
moda.user_id = "user_456"

async def main():
    options = ClaudeAgentOptions(model="claude-sonnet-4-20250514")

    async with ClaudeSDKClient(options=options) as client:
        await client.query("What is the capital of France?")

        async for msg in client.receive_response():
            print(msg)

asyncio.run(main())

moda.flush()
```

## Supported Features

| Feature             | Captured                                           |
| ------------------- | -------------------------------------------------- |
| Agent sessions      | Yes                                                |
| Streaming responses | Yes                                                |
| Tool use tracking   | Yes (count of tool calls across turns)             |
| Token usage         | Yes (input, output, total, including cache tokens) |
| Model name          | Yes (request and response)                         |
| Session ID          | Yes                                                |
| Turn count          | Yes                                                |

## Data Captured

| Attribute                      | Description                                |
| ------------------------------ | ------------------------------------------ |
| `gen_ai.request.model`         | Requested model name                       |
| `gen_ai.response.model`        | Actual model used in response              |
| `gen_ai.usage.input_tokens`    | Input token count (including cache tokens) |
| `gen_ai.usage.output_tokens`   | Output token count                         |
| `llm.usage.total_tokens`       | Total token count                          |
| `claude_agent.num_turns`       | Number of conversation turns               |
| `claude_agent.session_id`      | Agent session identifier                   |
| `claude_agent.tool_call_count` | Total tool calls across all turns          |
| `moda.conversation_id`         | Conversation ID (when set)                 |
| `moda.user_id`                 | User ID (when set)                         |

## Troubleshooting

**Data not appearing?**

* Make sure you installed `moda-claude-agent-sdk` separately, it is not included with `moda-ai`
* Ensure `moda.init()` is called before creating the `ClaudeSDKClient`
* Call `moda.flush()` before your program exits

**Token counts missing?**

* Token usage comes from the `ResultMessage` at the end of the stream. Make sure you consume the full async generator from `receive_response()`

**No spans generated?**

* Verify that `claude-agent-sdk` is installed and importable
* Check that the instrumentor is active: `moda.init()` automatically enables it when the package is installed

<Info>
  For full SDK documentation, see the [Python SDK](/ingestion/moda-sdk) guide.
</Info>