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

# Claude Agent SDK

> Instrumente o Claude Agent SDK com hooks do OpenTelemetry para capturar traces no Toqan Router e roteie as chamadas ao Claude pelo AI Gateway.

> [card] [Observabilidade](#observability)
>
> Instrumente seus agentes com OpenTelemetry usando o sistema de hooks do SDK para capturar traces de cada turno do agente e uso de ferramenta.

> [card] [AI Gateway  Beta](#ai-gateway)
>
> Roteie suas chamadas ao Claude pelo **AI Gateway** alterando apenas a URL base. Sem dependência de fornecedor: rode sempre no melhor modelo, com o menor custo para o seu caso de uso.

## Observabilidade

### Visão geral

O Claude Agent SDK (`claude-agent-sdk`) controla a CLI do Claude como um agente programável, com suporte a conversas de múltiplos turnos, uso de ferramentas e servidores MCP. Use o sistema de `hooks` integrado do SDK para acoplar a instrumentação do OpenTelemetry em pontos-chave da execução. Cada invocação de ferramenta vira um span, e todo o fluxo de trabalho do agente é capturado como um trace no **Toqan Router**, sem modificar a lógica do seu agente.

### Principais benefícios

> [card] Visibilidade total do agente
>
> Acompanhe cada turno do agente, uso de ferramenta e chamada de LLM com traces e analytics detalhados

> [card] Nenhuma alteração de código
>
> Adicione observabilidade por meio de hooks sem modificar a lógica do seu agente

> [card] Rastreamento de custos
>
> Custo e uso de tokens em tempo real por execução de agente, sincronizados com o Toqan Router

> [card] Inspeção de ferramentas
>
> Inspecione cada entrada e saída de ferramenta com o contexto completo da execução

### Pré-requisitos

* Uma conta do Toqan Router e uma chave de API
* Python 3.10 ou superior, ou Node.js 18 ou superior
* [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code/getting-started) instalada e autenticada

> [!NOTE]
>
> Para configurar sua chave de API, consulte Chaves de API e endpoints.

### Instalar dependências

> [tab] TypeScript
>
> ```bash npm theme={"theme":{"light":"github-light","dark":"github-dark"}}
> npm install @anthropic-ai/claude-agent-sdk \
>             @arizeai/openinference-instrumentation-claude-agent-sdk \
>             @opentelemetry/sdk-node \
>             @opentelemetry/exporter-trace-otlp-http
> ```
>
> ```bash pnpm theme={"theme":{"light":"github-light","dark":"github-dark"}}
> pnpm add @anthropic-ai/claude-agent-sdk \
>          @arizeai/openinference-instrumentation-claude-agent-sdk \
>          @opentelemetry/sdk-node \
>          @opentelemetry/exporter-trace-otlp-http
> ```
>
> ```bash bun theme={"theme":{"light":"github-light","dark":"github-dark"}}
> bun add @anthropic-ai/claude-agent-sdk \
>         @arizeai/openinference-instrumentation-claude-agent-sdk \
>         @opentelemetry/sdk-node \
>         @opentelemetry/exporter-trace-otlp-http
> ```

> [tab] Python
>
> ```bash uv theme={"theme":{"light":"github-light","dark":"github-dark"}}
> uv add claude-agent-sdk openinference-instrumentation-claude-agent-sdk \
>        opentelemetry-sdk opentelemetry-exporter-otlp
> ```
>
> ```bash pip theme={"theme":{"light":"github-light","dark":"github-dark"}}
> pip install claude-agent-sdk openinference-instrumentation-claude-agent-sdk \
>             opentelemetry-sdk opentelemetry-exporter-otlp
> ```

### Configuração

Configure o tracer provider do OTel para exportar spans ao Toqan Router:

> [tab] TypeScript
>
> ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> import { NodeSDK } from '@opentelemetry/sdk-node';
> import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
> import { ClaudeAgentSDKInstrumentation } from '@arizeai/openinference-instrumentation-claude-agent-sdk';
> import * as ClaudeAgentSDKModule from '@anthropic-ai/claude-agent-sdk';
>
> const ClaudeAgentSDK = { ...ClaudeAgentSDKModule };
> const instrumentation = new ClaudeAgentSDKInstrumentation();
> instrumentation.manuallyInstrument(ClaudeAgentSDK);
>
> const sdk = new NodeSDK({
>   traceExporter: new OTLPTraceExporter({
>     url: 'https://router.toqan.ai/eu/v2/otel/v1/traces',
>     headers: {
>       Authorization: `Bearer ${process.env.TOQAN_API_KEY}`,
>     },
>   }),
>   instrumentations: [instrumentation],
> });
>
> sdk.start();
> ```

> [tab] Python
>
> ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
> import os
> from opentelemetry.sdk.trace import TracerProvider
> from opentelemetry.sdk.trace.export import BatchSpanProcessor
> from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
> from opentelemetry import trace
> from openinference.instrumentation.claude_agent_sdk import ClaudeAgentSDKInstrumentor
>
> tracer_provider = TracerProvider()
> tracer_provider.add_span_processor(
>     BatchSpanProcessor(
>         OTLPSpanExporter(
>             endpoint="https://router.toqan.ai/eu/v2/otel/v1/traces",
>             headers={"Authorization": f"Bearer {os.environ['TOQAN_API_KEY']}"},
>         )
>     )
> )
> trace.set_tracer_provider(tracer_provider)
>
> ClaudeAgentSDKInstrumentor().instrument(tracer_provider=tracer_provider)
> tracer = trace.get_tracer(__name__)
> ```

### Exemplo básico

> [tab] TypeScript
>
> Espalhe o módulo do SDK importado em um namespace mutável e depois chame `ClaudeAgentSDKInstrumentation.manuallyInstrument(...)` antes de `sdk.start()`. A instrumentação transforma automaticamente cada chamada `query()`, uso de ferramenta e subagente em spans.
>
> ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> import { NodeSDK } from '@opentelemetry/sdk-node';
> import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
> import { ClaudeAgentSDKInstrumentation } from '@arizeai/openinference-instrumentation-claude-agent-sdk';
> import * as ClaudeAgentSDKModule from '@anthropic-ai/claude-agent-sdk';
>
> const ClaudeAgentSDK = { ...ClaudeAgentSDKModule };
> const instrumentation = new ClaudeAgentSDKInstrumentation();
> instrumentation.manuallyInstrument(ClaudeAgentSDK);
>
> const sdk = new NodeSDK({
>   traceExporter: new OTLPTraceExporter({
>     url: 'https://router.toqan.ai/eu/v2/otel/v1/traces',
>     headers: {
>       Authorization: `Bearer ${process.env.TOQAN_API_KEY}`,
>     },
>   }),
>   instrumentations: [instrumentation],
> });
>
> sdk.start();
>
> const prompt = 'What is the capital of France?';
> console.log(`User: ${prompt}\n`);
>
> for await (const message of ClaudeAgentSDK.query({ prompt })) {
>   if ('result' in message && typeof message.result === 'string') {
>     console.log(`Assistant: ${message.result}`);
>   }
> }
>
> await sdk.shutdown();
> console.log('\nTraces exported to Toqan Router. View them at https://router.toqan.ai/eu');
> ```

> [tab] Python
>
> Chame `ClaudeAgentSDKInstrumentor().instrument()` antes de qualquer chamada ao agente. O instrumentor envolve automaticamente cada invocação de ferramenta, turno de LLM e subagente em spans. Controle o agente via `ClaudeSDKClient` (em vez do gerador `query()` independente) e envolva a chamada em um span raiz `agent-workflow` para registrar o prompt e o custo final.
>
> ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
> import asyncio
> import os
> from claude_agent_sdk import (
>     ClaudeAgentOptions,
>     ClaudeSDKClient,
>     AssistantMessage,
>     TextBlock,
>     ResultMessage,
> )
> from openinference.instrumentation.claude_agent_sdk import ClaudeAgentSDKInstrumentor
> from opentelemetry.sdk.trace import TracerProvider
> from opentelemetry.sdk.trace.export import BatchSpanProcessor
> from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
> from opentelemetry import trace
>
> tracer_provider = TracerProvider()
> tracer_provider.add_span_processor(
>     BatchSpanProcessor(
>         OTLPSpanExporter(
>             endpoint="https://router.toqan.ai/eu/v2/otel/v1/traces",
>             headers={"Authorization": f"Bearer {os.environ['TOQAN_API_KEY']}"},
>         )
>     )
> )
> trace.set_tracer_provider(tracer_provider)
>
> ClaudeAgentSDKInstrumentor().instrument(tracer_provider=tracer_provider)
> tracer = trace.get_tracer(__name__)
>
>
> async def main():
>     options = ClaudeAgentOptions(
>         model="sonnet",
>         system_prompt="You are a helpful coding assistant.",
>         max_turns=3,
>         allowed_tools=["Read", "Bash"],
>     )
>
>     prompt = "What Python version is installed on this system?"
>     print(f"User: {prompt}\n")
>
>     with tracer.start_as_current_span("agent-workflow") as span:
>         span.set_attribute("agent.prompt", prompt)
>
>         async with ClaudeSDKClient(options=options) as client:
>             await client.query(prompt)
>             async for message in client.receive_response():
>                 if isinstance(message, AssistantMessage):
>                     for block in message.content:
>                         if isinstance(block, TextBlock):
>                             print(f"Assistant: {block.text}")
>                 elif isinstance(message, ResultMessage):
>                     span.set_attribute("agent.total_cost_usd", message.total_cost_usd or 0)
>                     span.set_attribute("agent.num_turns", message.num_turns)
>                     print(f"\nCost: ${message.total_cost_usd or 0:.6f} | Turns: {message.num_turns}")
>
>     tracer_provider.force_flush()
>     print("\nTraces exported to Toqan Router. View them at https://router.toqan.ai/eu")
>
>
> asyncio.run(main())
> ```

### Ver traces

Veja seus traces no [AI Studio](/docs/pt-BR/ai-studio/observability/quickstart.md), na aba **Traces**.

> [!NOTE]
>
> Acesse o seu [AI Studio](https://router.toqan.ai/eu) para ver analytics e traces em tempo real.

## AI Gateway

> [!WARNING]
>
> Este recurso está em Beta. Os traces não são suportados ao usar o AI Gateway com o Claude Agent SDK.

### Visão geral

Roteie as chamadas de modelo do Claude Agent SDK pelo **AI Gateway** do **Toqan Router** sem alterar nenhuma lógica do agente. O SDK controla a CLI do Claude, que lê `ANTHROPIC_BASE_URL` e `ANTHROPIC_AUTH_TOKEN` do ambiente; assim, apontar essas variáveis para o gateway faz cada turno passar pelo **Toqan Router**.

> [!NOTE]
>
> Para usar a Claude Messages API diretamente, sem o runtime de agente, consulte a integração com o [SDK da Anthropic](/docs/pt-BR/ai-studio/integrations/frameworks/anthropic.md).

### Configuração

Defina as seguintes variáveis de ambiente antes de executar o agente:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export ANTHROPIC_BASE_URL="https://router.toqan.ai/eu/v3/anthropic"
export ANTHROPIC_AUTH_TOKEN="$TOQAN_API_KEY"
export ANTHROPIC_API_KEY=""  # set empty so the SDK does not call the Anthropic API directly
export ANTHROPIC_MODEL="anthropic/claude-sonnet-5"  # the anthropic/ prefix is required
```

### Exemplo básico

Com as variáveis de ambiente definidas, cada execução do agente passa pelo **AI Gateway**, sem alterações no código que faz a chamada:

> [tab] TypeScript
>
> ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> import { query } from '@anthropic-ai/claude-agent-sdk';
>
> const prompt = 'What is the capital of France?';
>
> for await (const message of query({ prompt })) {
>   if ('result' in message && typeof message.result === 'string') {
>     console.log(message.result);
>   }
> }
> ```

> [tab] Python
>
> ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
> import asyncio
> from claude_agent_sdk import (
>     ClaudeSDKClient,
>     AssistantMessage,
>     TextBlock,
> )
>
>
> async def main():
>     async with ClaudeSDKClient() as client:
>         await client.query("What is the capital of France?")
>         async for message in client.receive_response():
>             if isinstance(message, AssistantMessage):
>                 for block in message.content:
>                     if isinstance(block, TextBlock):
>                         print(block.text)
>
>
> asyncio.run(main())
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.