View a markdown version of this page

SDK do Claude Agent - Amazon Bedrock AgentCore
Instrumente seu agenteComo os vãos são identificadosComo os campos de avaliação são extraídosExemplos de períodos com registros de eventosExemplos de períodos sem registros de eventos

SDK do Claude Agent

Esta página explica como instrumentar um agente do SDK do Claude Agent, como os intervalos são identificados e como os campos de avaliação são extraídos.

Tópicos

Instrumente seu agente

Você pode instrumentar um agente SDK do Claude Agent com a biblioteca de OpenInferenceinstrumentaçã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 observabilidade.

Como os vãos são identificados

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

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.

A partir de registros de eventos

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.

A partir de atributos de extensão

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 ferramentatool.name, o ID da chamada da ferramenta de tool.idinput.value, os argumentos e o resultado deoutput.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.

Exemplos de períodos com registros de eventos

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.

exemplo
Invoke agent span

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

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

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.

exemplo
Invoke agent span

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

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