Claude Agent SDK

Observabilidade

Instrumente seus agentes com OpenTelemetry usando o sistema de hooks do SDK para capturar traces de cada turno do agente e uso de ferramenta.

AI Gateway Beta

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

Visibilidade total do agente

Acompanhe cada turno do agente, uso de ferramenta e chamada de LLM com traces e analytics detalhados

Nenhuma alteração de código

Adicione observabilidade por meio de hooks sem modificar a lógica do seu agente

Rastreamento de custos

Custo e uso de tokens em tempo real por execução de agente, sincronizados com o Toqan Router

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 instalada e autenticada

Para configurar sua chave de API, consulte Chaves de API e endpoints.

Instalar dependências

TypeScript
Python

npm install @anthropic-ai/claude-agent-sdk \
            @arizeai/openinference-instrumentation-claude-agent-sdk \
            @opentelemetry/sdk-node \
            @opentelemetry/exporter-trace-otlp-http

pnpm add @anthropic-ai/claude-agent-sdk \
         @arizeai/openinference-instrumentation-claude-agent-sdk \
         @opentelemetry/sdk-node \
         @opentelemetry/exporter-trace-otlp-http

bun add @anthropic-ai/claude-agent-sdk \
        @arizeai/openinference-instrumentation-claude-agent-sdk \
        @opentelemetry/sdk-node \
        @opentelemetry/exporter-trace-otlp-http

uv add claude-agent-sdk openinference-instrumentation-claude-agent-sdk \
       opentelemetry-sdk opentelemetry-exporter-otlp

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:

TypeScript
Python

TypeScript

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();

Python

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

TypeScript
Python

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

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');

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

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, na aba Traces.

Acesse o seu AI Studio para ver analytics e traces em tempo real.

AI Gateway

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.

Para usar a Claude Messages API diretamente, sem o runtime de agente, consulte a integração com o SDK da Anthropic.

Configuração

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

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:

TypeScript
Python

TypeScript

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);
  }
}

Python

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())

Visão geral

Instrumente seu app

Explorar

Monitorar

Exportar

Revisar

Privacidade e segurança de dados

Integrações com frameworks

Observabilidade

AI Gateway Beta

Observabilidade

Visão geral

Principais benefícios

Visibilidade total do agente

Nenhuma alteração de código

Rastreamento de custos

Inspeção de ferramentas

Pré-requisitos

Instalar dependências

Configuração

Exemplo básico

Ver traces

AI Gateway

Visão geral

Configuração

Exemplo básico

Observabilidade

AI Gateway Beta

​Observabilidade

​Visão geral

​Principais benefícios

Visibilidade total do agente

Nenhuma alteração de código

Rastreamento de custos

Inspeção de ferramentas

​Pré-requisitos

​Instalar dependências

​Configuração

​Exemplo básico

​Ver traces

​AI Gateway

​Visão geral

​Configuração

​Exemplo básico

Observabilidade

Visão geral

Principais benefícios

Pré-requisitos

Instalar dependências

Configuração

Exemplo básico

Ver traces

AI Gateway

Visão geral

Configuração

Exemplo básico