# SDK do Claude Agent
<a name="supported-frameworks-claude-agent-sdk"></a>

Esta página explica como instrumentar um [agente do SDK do Claude](https://docs.claude.com/en/api/agent-sdk/overview) Agent, como os intervalos são identificados e como os campos de avaliação são extraídos.

 **Tópicos** 
+  [Instrumente seu agente](#claude-agent-sdk-instrument) 
+  [Como os vãos são identificados](#claude-agent-sdk-span-identification) 
+  [Como os campos de avaliação são extraídos](#claude-agent-sdk-extraction) 
  +  [A partir de registros de eventos](#claude-agent-sdk-extraction-event-records) 
  +  [A partir de atributos de extensão](#claude-agent-sdk-extraction-attributes) 
+  [Exemplos de períodos com registros de eventos](#claude-agent-sdk-examples-with) 
+  [Exemplos de períodos sem registros de eventos](#claude-agent-sdk-examples-without) 

## Instrumente seu agente
<a name="claude-agent-sdk-instrument"></a>

Você pode instrumentar um agente SDK do Claude Agent com a biblioteca de **OpenInference**instrumentação (). `openinference-instrumentation-claude-agent-sdk` Essa biblioteca emite telemetria sob o nome do escopo, `openinference.instrumentation.claude_agent_sdk` que o Amazon Bedrock AgentCore Evaluations lê.

Quando seu agente é executado com a AWS Distro for OpenTelemetry (ADOT), como no Amazon Bedrock AgentCore Runtime, você não precisa adicionar código de instrumentação explícito. Adicionar a biblioteca de instrumentação às dependências do seu projeto é suficiente. O ADOT o descobre na inicialização e o ativa automaticamente.

Adicione a biblioteca de instrumentação às suas dependências.

**nota**  
Use a versão `0.1.3` ou posterior. Essa é a versão mais antiga testada com o serviço de avaliação.

 `requirements.txt`:

```
openinference-instrumentation-claude-agent-sdk>=0.1.3
```

 `pyproject.toml`:

```
[project]
dependencies = [
    "openinference-instrumentation-claude-agent-sdk>=0.1.3",
]
```

**nota**  
A instrumentação é uma etapa na configuração da observabilidade. Para exportar a telemetria para avaliação, conclua a configuração completa em [Configurar](supported-frameworks.md#supported-frameworks-setup) observabilidade.

## Como os vãos são identificados
<a name="claude-agent-sdk-span-identification"></a>

O Claude Agent SDK é instrumentado com a OpenInference convenção, então as AgentCore avaliações classificam as extensões usando o atributo. `openinference.span.kind`


| Tipo de extensão | Atributo de identificação | 
| --- | --- | 
| Invocar agente |  `openinference.span.kind` = `AGENT`  | 
| Ferramenta de execução |  `openinference.span.kind` = `TOOL`  | 

O SDK do Claude Agent emite somente `AGENT` e `TOOL` abrange; ele não emite períodos separados de inference (). `LLM` Os metadados do modelo (nome do modelo, uso do token) e a resposta do agente são transmitidos no próprio `AGENT` span.

## Como os campos de avaliação são extraídos
<a name="claude-agent-sdk-extraction"></a>

O SDK do Claude Agent produz entrada e saída de agente em texto simples e sem formatação, portanto, o prompt do usuário e a resposta do agente não exigem análise especial. Os resultados da ferramenta, no entanto, chegam como blocos de conteúdo antrópico no formulário`[{"type": "text", "text": "…​"}]`. AgentCore As avaliações desembrulham esses blocos e concatenam seu texto.

A localização desse conteúdo depende de como a telemetria foi coletada. O atributo de identificação (`openinference.span.kind`) está no intervalo em ambos os casos. Para obter mais informações, consulte [Espaços, registros de eventos e sinais de telemetria](supported-frameworks-telemetry.md).

### A partir de registros de eventos
<a name="claude-agent-sdk-extraction-event-records"></a>

Quando a telemetria é dividida, o AgentCore Evaluations lê o conteúdo do registro do evento correlacionado a cada período:
+  **Solicitação do usuário** e **resposta do agente**: do registro de eventos do invoke agent span, em `body.input` e. `body.output`
+  **Chamada** de ferramenta: o nome da ferramenta do `tool.name` atributo e o ID da chamada da ferramenta `tool.id` na extensão da ferramenta de execução. Os argumentos e o resultado da ferramenta vêm do registro de eventos desse intervalo, em `body.input` `body.output` e. AgentCore As avaliações revelam os blocos de conteúdo antrópico no resultado da ferramenta.

Para ver exemplos, consulte [Exemplos de períodos com registros de eventos](#claude-agent-sdk-examples-with).

### A partir de atributos de extensão
<a name="claude-agent-sdk-extraction-attributes"></a>

Quando a telemetria não é dividida, o mesmo conteúdo permanece na extensão como atributos:
+  **Solicitação do usuário** e **resposta do agente**: de `input.value` e `output.value` sobre o período de invocação do agente.
+  **Chamada** de ferramenta: o nome da ferramenta`tool.name`, o ID da chamada da ferramenta de `tool.id``input.value`, os argumentos e o resultado de`output.value`, na extensão da ferramenta de execução. AgentCore As avaliações revelam os blocos de conteúdo antrópico no resultado da ferramenta.

Por [exemplo, consulte Exemplos de períodos sem registros de eventos](#claude-agent-sdk-examples-without).

## Exemplos de períodos com registros de eventos
<a name="claude-agent-sdk-examples-with"></a>

Quando a telemetria é dividida, o intervalo carrega os atributos de identificação e o conteúdo fica em um registro de evento correlacionado. Os exemplos a seguir são de um agente de planejamento de viagens do Claude Agent SDK implantado no Amazon Bedrock Runtime. AgentCore 

**nota**  
Esses exemplos não são extensões completas. Eles mostram dados representativos de uma interação real do agente, com alguns campos omitidos e valores longos truncados para facilitar a leitura.

**Example**  
O `openinference.span.kind` atributo (`AGENT`) identifica isso como uma extensão do agente de invocação. O intervalo carrega os metadados do modelo; o conteúdo da conversa reside no registro do evento correlacionado.  

```
{
  "traceId": "6a292d74406894815807e2751e61dd49",
  "spanId": "a63aab3320ed8718",
  "name": "ClaudeAgentSDK.ClaudeSDKClient.receive_response",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.claude_agent_sdk",
    "version": "0.1.5"
  },
  "attributes": {
    "openinference.span.kind": "AGENT",
    "llm.system": "anthropic",
    "llm.model_name": "us.anthropic.claude-sonnet-4-5-20250929-v1:0",
    "input.mime_type": "text/plain",
    "output.mime_type": "text/plain",
    "session.id": "sea-nyc-trip-2-turns-claude-adot"
  },
  "status": {
    "code": "OK"
  }
}
```

```
{
  "spanId": "a63aab3320ed8718",
  "traceId": "6a292d74406894815807e2751e61dd49",
  "scope": {
    "name": "openinference.instrumentation.claude_agent_sdk"
  },
  "body": {
    "input": {
      "messages": [
        { "role": "user", "content": "Hey, how can you help me" }
      ]
    },
    "output": {
      "messages": [
        { "role": "assistant", "content": "Hello! I'm your travel planning assistant ..." }
      ]
    }
  }
}
```
O `openinference.span.kind` atributo (`TOOL`) identifica isso como uma extensão da ferramenta de execução; `tool.name` contém o nome da ferramenta e `tool.id` o ID da chamada da ferramenta. O resultado da ferramenta está no registro de eventos correlacionados como blocos de conteúdo antrópico, que as AgentCore avaliações desembrulham.  

```
{
  "traceId": "6a292deb7450b3155895da4f38cb579a",
  "spanId": "909dcb4eb5f851ae",
  "name": "mcp__travel__search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.claude_agent_sdk",
    "version": "0.1.5"
  },
  "attributes": {
    "openinference.span.kind": "TOOL",
    "tool.name": "mcp__travel__search_flights",
    "tool.id": "toolu_bdrk_01KmJhCRuEJJo6fswHbjCgFp",
    "tool.parameters": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "input.mime_type": "application/json",
    "output.mime_type": "application/json",
    "session.id": "sea-nyc-trip-2-turns-claude-adot"
  },
  "status": {
    "code": "OK"
  }
}
```

```
{
  "spanId": "909dcb4eb5f851ae",
  "traceId": "6a292deb7450b3155895da4f38cb579a",
  "scope": {
    "name": "openinference.instrumentation.claude_agent_sdk"
  },
  "body": {
    "input": {
      "messages": [
        { "role": "user", "content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}" }
      ]
    },
    "output": {
      "messages": [
        {
          "role": "assistant",
          "content": "[{\"type\": \"text\", \"text\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\"}]"
        }
      ]
    }
  }
}
```

## Exemplos de períodos sem registros de eventos
<a name="claude-agent-sdk-examples-without"></a>

Quando a telemetria não é dividida, o mesmo conteúdo permanece nos atributos de span e nenhum registro de evento separado é produzido. Os exemplos a seguir são de um agente de planejamento de viagens do Claude Agent SDK.

**nota**  
Esses exemplos não são extensões completas. Eles mostram dados representativos de uma interação real do agente, com alguns campos omitidos e valores longos truncados para facilitar a leitura.

**Example**  
O `input.value` atributo contém o prompt do usuário e o `output.value` atributo contém a resposta do agente, ambos como texto sem formatação.  

```
{
  "traceId": "561876bb17e9eaeb2f194ee515742b2f",
  "spanId": "3b6815f5b3909a51",
  "name": "ClaudeAgentSDK.ClaudeSDKClient.receive_response",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.claude_agent_sdk",
    "version": "0.1.3"
  },
  "attributes": {
    "openinference.span.kind": "AGENT",
    "llm.system": "anthropic",
    "llm.model_name": "us.anthropic.claude-sonnet-4-5-20250929-v1:0",
    "input.value": "Hey, how can you help me",
    "input.mime_type": "text/plain",
    "output.value": "Hi there! ... How can I help you plan your next adventure?",
    "output.mime_type": "text/plain",
    "session.id": "sea-nyc-trip-2-turns-claude-unified"
  },
  "status": {
    "code": "OK"
  }
}
```
O `input.value` atributo contém os argumentos da ferramenta e o `output.value` atributo contém o resultado da ferramenta como blocos de conteúdo antrópico, que AgentCore as avaliações desembrulham.  

```
{
  "traceId": "7bb7e59a30d03fc0b9da5bf009a3b429",
  "spanId": "d27b488965bbba99",
  "name": "mcp__travel__search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.claude_agent_sdk",
    "version": "0.1.3"
  },
  "attributes": {
    "openinference.span.kind": "TOOL",
    "tool.name": "mcp__travel__search_flights",
    "tool.id": "toolu_bdrk_019yE7Gne1rZKE3UnVPAWjLq",
    "tool.parameters": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "input.value": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "input.mime_type": "application/json",
    "output.value": "[{\"type\": \"text\", \"text\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\"}]",
    "output.mime_type": "application/json",
    "session.id": "sea-nyc-trip-2-turns-claude-unified"
  },
  "status": {
    "code": "OK"
  }
}
```