View a markdown version of this page

Claude Agent SDK - Amazon Bedrock AgentCore
Individua il tuo agenteCome vengono identificati gli intervalliCome vengono estratti i campi di valutazioneEsempi di intervalli nella telemetria divisaEsempi di intervalli di telemetria unificata

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Claude Agent SDK

Questa pagina spiega come utilizzare un agente Claude Agent SDK, come vengono identificati gli intervalli e come vengono estratti i campi di valutazione.

Argomenti

Individua il tuo agente

Puoi strumentare un agente Claude Agent SDK con la libreria di OpenInference strumentazione (). openinference-instrumentation-claude-agent-sdk Questa libreria emette dati di telemetria con il nome dell'ambito, che viene letto da Amazon Bedrock Evaluations. openinference.instrumentation.claude_agent_sdk AgentCore

Quando l'agente viene eseguito con AWS Distro for OpenTelemetry (ADOT), ad esempio su Amazon Bedrock AgentCore Runtime, non è necessario aggiungere codice di strumentazione esplicito. È sufficiente aggiungere la libreria di strumentazione alle dipendenze del progetto. ADOT la rileva all'avvio e la attiva automaticamente.

Aggiungi la libreria di strumentazione alle tue dipendenze.

Nota

Usa la versione 0.1.3 o successiva. Questa è la prima versione testata con il servizio di valutazione.

requirements.txt:

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

pyproject.toml:

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

La strumentazione è un passo verso l'impostazione dell'osservabilità. Per esportare la telemetria per la valutazione, completa la configurazione completa in Imposta l'osservabilità. Imposta l'osservabilità

Come vengono identificati gli intervalli

Claude Agent SDK è basato sulla OpenInference convenzione, quindi AgentCore Evaluations classifica gli intervalli utilizzando l'attributo. openinference.span.kind

Tipo di intervallo Attributo identificativo

Invoca l'agente

openinference.span.kind = AGENT

Strumento di esecuzione

openinference.span.kind = TOOL

L'SDK Claude Agent emette solo dati AGENT e si TOOL estende; non emette intervalli di inferenza () separati. LLM I metadati del modello (nome del modello, utilizzo del token) e la risposta dell'agente vengono trasferiti nell'intervallo stesso. AGENT

Come vengono estratti i campi di valutazione

L'SDK Claude Agent produce input e output di agenti in testo semplice e pulito, pertanto il prompt dell'utente e la risposta dell'agente non richiedono un'analisi speciale. I risultati degli strumenti, tuttavia, arrivano sotto forma di blocchi di contenuto antropico nel modulo. [{"type": "text", "text": "…​"}] AgentCore Evaluations estrae questi blocchi e ne concatena il testo.

La posizione di questo contenuto dipende dal modo in cui è stata raccolta la telemetria. L'attributo identificativo (openinference.span.kind) si trova nello span in entrambi i casi. Per ulteriori informazioni, vedere Configurazione e consegna della telemetria.

Dai registri degli eventi

Con la telemetria divisa, AgentCore Evaluations legge il contenuto del record dell'evento correlato a ciascun intervallo:

  • Richiesta dell'utente e risposta dell'agente: dal record degli eventi di invoke agent span, in e. body.input body.output

  • Chiamata allo strumento: il nome dello strumento in tool.id base all'tool.nameattributo e l'ID della chiamata allo strumento di esecuzione nell'intervallo dello strumento di esecuzione. Gli argomenti e i risultati dello strumento provengono dal record degli eventi di quell'intervallo, in body.input e. body.output AgentCore Le valutazioni separano i blocchi di contenuto di Anthropic dal risultato dello strumento.

Per ulteriori informazioni, consulta Esempi di intervalli di telemetria divisa.

Dagli attributi span

Con la telemetria unificata, lo stesso contenuto rimane nello span degli attributi:

  • Richiesta dell'utente e risposta dell'agente: da input.value e verso l'intervallo dell'agente output.value invoke.

  • Chiamata allo strumento: il nome dello strumento datool.name, l'ID della chiamata allo strumento datool.id, gli argomenti da input.value e il risultato dioutput.value, nell'intervallo di esecuzione dello strumento. AgentCore Le valutazioni separano i blocchi di contenuto antropico dal risultato dello strumento.

Per ulteriori informazioni, consulta Esempi di intervalli nella telemetria unificata.

Esempi di intervalli nella telemetria divisa

Con la telemetria divisa, l'intervallo riporta gli attributi identificativi e il contenuto risiede in un record di eventi correlato. I seguenti esempi sono tratti da un agente Claude Agent SDK per la pianificazione dei viaggi distribuito su Amazon Bedrock Runtime. AgentCore

Nota

Questi esempi non sono intervalli completi. Mostrano dati rappresentativi di un'interazione con un agente reale, con alcuni campi omessi e valori lunghi troncati per motivi di leggibilità.

Esempio
Invoke agent span

L'openinference.span.kindattributo (AGENT) lo identifica come un invoke agent span. L'intervallo contiene i metadati del modello; il contenuto della conversazione risiede nel record dell'evento correlato.

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

L'openinference.span.kindattributo (TOOL) lo identifica come un intervallo di esecuzione dello strumento; tool.name contiene il nome dello strumento e l'ID della chiamata dello strumento. tool.id Il risultato dello strumento risiede nel record dell'evento correlato sotto forma di blocchi di contenuto antropico, che Evaluations analizza. AgentCore 

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

Esempi di intervalli di telemetria unificata

Con la telemetria unificata, lo stesso contenuto rimane negli attributi span e non viene prodotto alcun record di evento separato. I seguenti esempi sono tratti da un agente Claude Agent SDK per la pianificazione dei viaggi.

Nota

Questi esempi non sono intervalli completi. Mostrano dati rappresentativi di un'interazione con un agente reale, con alcuni campi omessi e valori lunghi troncati per motivi di leggibilità.

Esempio
Invoke agent span

L'input.valueattributo contiene il prompt dell'utente e l'output.valueattributo contiene la risposta dell'agente, entrambi in testo normale.

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

L'input.valueattributo contiene gli argomenti dello strumento e l'output.valueattributo contiene il risultato dello strumento sotto forma di blocchi di contenuto antropico, che AgentCore Evaluations analizza.

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