View a markdown version of this page

Claude Agent SDK - Amazon Bedrock AgentCore
Instrumente a su agenteCómo se identifican los intervalosCómo se extraen los campos de evaluaciónUn ejemplo de tramos con registros de eventosEjemplos de intervalos sin registros de eventos

Claude Agent SDK

En esta página, se explica cómo instrumentar un agente del SDK de Claude Agent, cómo se identifican los intervalos y cómo se extraen los campos de evaluación.

Temas

Instrumente a su agente

Puede instrumentar un agente del SDK de Claude Agent con la biblioteca de OpenInferenceinstrumentació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.

Cómo se identifican los intervalos

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

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.

De los registros de eventos

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 ybody.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.

De los atributos de span

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 origentool.name, el identificador de tool.id la llamada a la herramienta de origeninput.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.

Un ejemplo de tramos con registros de eventos

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.

ejemplo
Invoke agent span

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 ..." }
      ]
    }
  }
}
Execute tool span

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

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.

ejemplo
Invoke agent span

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"
  }
}
Execute tool span

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