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

En esta página, se explica cómo instrumentar un [agente del SDK de Claude](https://docs.claude.com/en/api/agent-sdk/overview) Agent, cómo se identifican los intervalos y cómo se extraen los campos de evaluación.

 **Temas** 
+  [Instrumente a su agente](#claude-agent-sdk-instrument) 
+  [¿Cómo se identifican los tramos](#claude-agent-sdk-span-identification) 
+  [Cómo se extraen los campos de evaluación](#claude-agent-sdk-extraction) 
  +  [De los registros de eventos](#claude-agent-sdk-extraction-event-records) 
  +  [De los atributos de span](#claude-agent-sdk-extraction-attributes) 
+  [Ejemplos de tramos con registros de eventos](#claude-agent-sdk-examples-with) 
+  [Ejemplos de tramos sin registros de eventos](#claude-agent-sdk-examples-without) 

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

Puede instrumentar un agente del SDK de Claude Agent con la biblioteca de **OpenInference**instrumentación (`openinference-instrumentation-claude-agent-sdk`). Esta biblioteca emite telemetría con el nombre del ámbito, `openinference.instrumentation.claude_agent_sdk` que se lee en Amazon Bedrock AgentCore Evaluations.

Cuando su agente utiliza la AWS Distro for OpenTelemetry (ADOT), como en Amazon Bedrock AgentCore Runtime, no necesita añadir código de instrumentación explícito. Basta con añadir la biblioteca de instrumentación a las dependencias de su proyecto. ADOT la descubre al inicio y la activa automáticamente.

Añada la biblioteca de instrumentación a sus dependencias.

**nota**  
Utilice la versión `0.1.3` o posterior. Esta es la primera versión probada con el servicio de evaluación.

 `requirements.txt`:

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

 `pyproject.toml`:

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

**nota**  
La instrumentación es un paso para configurar la observabilidad. [Para exportar la telemetría para su evaluación, complete la configuración completa en Configurar la observabilidad.](supported-frameworks.md#supported-frameworks-setup)

## Cómo se identifican los intervalos
<a name="claude-agent-sdk-span-identification"></a>

El SDK de Claude Agent está equipado con la OpenInference convención, por lo que AgentCore Evaluations clasifica los intervalos mediante el atributo. `openinference.span.kind`


| Tipo de tramo | Atributo identificativo | 
| --- | --- | 
| Invoca al agente |  `openinference.span.kind` = `AGENT`  | 
| Ejecute la herramienta |  `openinference.span.kind` = `TOOL`  | 

El SDK de Claude Agent solo emite `AGENT` y `TOOL` abarca; no emite intervalos de inferencia () `LLM` separados. Los metadatos del modelo (nombre del modelo, uso del token) y la respuesta del agente se incluyen en el propio intervalo. `AGENT`

## Cómo se extraen los campos de evaluación
<a name="claude-agent-sdk-extraction"></a>

El SDK de Claude Agent produce entradas y salidas de agentes limpias y en texto plano, por lo que el mensaje del usuario y la respuesta del agente no requieren un análisis especial. Sin embargo, los resultados de las herramientas se presentan en forma de bloques de contenido antrópico en el formulario. `[{"type": "text", "text": "…​"}]` AgentCore Las evaluaciones desenvuelven estos bloques y concatenan su texto.

La ubicación de este contenido depende de cómo se recopiló la telemetría. El atributo de identificación (`openinference.span.kind`) está en el intervalo en ambos casos. Para obtener más información, consulte [Intervalos, registros de eventos y señales de telemetría](supported-frameworks-telemetry.md).

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

Cuando se divide la telemetría, AgentCore Evaluations lee el contenido del registro de eventos correlacionado con cada intervalo:
+  **Mensaje del usuario** y **respuesta del agente**: del registro de eventos del intervalo de agentes invocado, en y. `body.input` `body.output`
+  **Llamada a la herramienta**: el nombre de la herramienta que aparece en el `tool.name` atributo y el identificador de llamada a la herramienta que aparece `tool.id` en el intervalo de herramientas de ejecución. Los argumentos y el resultado de la herramienta provienen del registro de eventos de ese intervalo, en `body.input` y`body.output`. AgentCore Las evaluaciones muestran los bloques de contenido antrópico del resultado de la herramienta.

Para ver ejemplos, consulte [Ejemplos de intervalos con registros de eventos.](#claude-agent-sdk-examples-with)

### De los atributos de span
<a name="claude-agent-sdk-extraction-attributes"></a>

Cuando la telemetría no está dividida, el mismo contenido permanece en el intervalo que los atributos:
+  **Mensaje del usuario** y **respuesta del agente**: desde `input.value` y `output.value` en el intervalo de invocación del agente.
+  **Llamada a** la herramienta: el nombre de la herramienta de origen`tool.name`, el identificador de `tool.id` la llamada a la herramienta de origen`input.value`, los argumentos y el resultado de `output.value` la misma en el intervalo de la herramienta de ejecución. AgentCore Las evaluaciones muestran los bloques de contenido antrópico del resultado de la herramienta.

Para ver ejemplos, consulte [Ejemplos de intervalos sin registros de eventos.](#claude-agent-sdk-examples-without)

## Un ejemplo de tramos con registros de eventos
<a name="claude-agent-sdk-examples-with"></a>

Cuando se divide la telemetría, el intervalo contiene los atributos de identificación y el contenido reside en un registro de eventos correlacionado. Los siguientes ejemplos provienen de un agente de planificación de viajes del SDK de Claude Agent implementado en Amazon Bedrock AgentCore Runtime.

**nota**  
Estos ejemplos no son períodos completos. Muestran datos representativos de una interacción real entre agentes, omitiendo algunos campos y truncando los valores largos para facilitar la lectura.

**Example**  
El `openinference.span.kind` atributo (`AGENT`) lo identifica como un intervalo de agentes de invocación. El intervalo contiene los metadatos del modelo; el contenido de la conversación reside en el registro de eventos correlacionados.  

```
{
  "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 ..." }
      ]
    }
  }
}
```
El `openinference.span.kind` atributo (`TOOL`) lo identifica como un intervalo de herramientas de ejecución; `tool.name` contiene el nombre de la herramienta y el identificador de llamada a `tool.id` la herramienta. El resultado de la herramienta se encuentra en el registro de eventos correlacionados como bloques de contenido antrópico, que AgentCore Evaluations desvela.  

```
{
  "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\\\": [ ... ]}\"}]"
        }
      ]
    }
  }
}
```

## Ejemplos de intervalos sin registros de eventos
<a name="claude-agent-sdk-examples-without"></a>

Cuando la telemetría no está dividida, el mismo contenido permanece en los atributos del tramo y no se genera ningún registro de eventos independiente. Los siguientes ejemplos son de un agente de planificación de viajes del SDK de Claude Agent.

**nota**  
Estos ejemplos no son tramos completos. Muestran datos representativos de una interacción real entre agentes, omitiendo algunos campos y truncando los valores largos para facilitar la lectura.

**Example**  
El `input.value` atributo contiene el mensaje del usuario y la `output.value` respuesta del agente, ambos en texto plano.  

```
{
  "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"
  }
}
```
El `input.value` atributo contiene los argumentos de la herramienta y el `output.value` atributo contiene el resultado de la herramienta en forma de bloques de contenido antrópico, que AgentCore Evaluations desglosa.  

```
{
  "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"
  }
}
```