View a markdown version of this page

Claude Agent SDK - Amazon Bedrock AgentCore
Strumenta il tuo agenteCome vengono identificati gli intervalliCome vengono estratti i campi di valutazioneL'esempio si estende ai record degli eventiL'esempio si estende senza record di eventi

Claude Agent SDK

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

Argomenti

Strumenta il tuo agente

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

Quando il tuo agente utilizza 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à.

Come vengono identificati gli intervalli

Claude Agent SDK utilizza questa 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 di Claude Agent emette solo 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 all'intervallo stesso. AGENT

Come vengono estratti i campi di valutazione

L'SDK di Claude Agent produce input e output di agenti in testo semplice e puliti, quindi il prompt dell'utente e la risposta dell'agente non richiedono un'analisi speciale. I risultati dello strumento, tuttavia, arrivano sotto forma di blocchi di contenuto Anthropic nel modulo. [{"type": "text", "text": "…​"}] AgentCore Evaluations rimuove 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) è compreso nell'intervallo in entrambi i casi. Per ulteriori informazioni, consulta Spans, record di eventi e segnali di telemetria.

Dai registri degli eventi

Quando la telemetria viene suddivisa, 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 and. body.input body.output

  • Chiamata allo strumento: il nome dello strumento dall'tool.nameattributo e l'ID della chiamata allo strumento dall'intervallo tool.id di esecuzione dello strumento. Gli argomenti e i risultati dello strumento provengono dal record degli eventi di quell'intervallo, in body.input and. body.output AgentCore Evaluations elimina i blocchi di contenuto di Anthropic nel risultato dello strumento.

Per esempi, vedete Example spans with event records.

Dagli attributi span

Quando la telemetria non viene suddivisa, lo stesso contenuto rimane nell'intervallo degli attributi:

  • Richiesta dell'utente e risposta dell'agente: da input.value e output.value sull'intervallo dell'agente 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 da output.value nell'intervallo dello strumento di esecuzione. AgentCore Evaluations elimina i blocchi di contenuto di Anthropic nel risultato dello strumento.

Per esempi, vedete Example spans without event records.

L'esempio si estende ai record degli eventi

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

Nota

Questi esempi non sono intervalli completi. Mostrano dati rappresentativi derivanti da 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. Lo span 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 uno strumento di esecuzione; tool.name contiene il nome dello strumento e tool.id l'ID della chiamata dello strumento. Il risultato dello strumento risiede nel record degli eventi correlato sotto forma di blocchi di contenuto Anthropic, che Evaluations elimina. 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\\\": [ ... ]}\"}]"
        }
      ]
    }
  }
}

L'esempio si estende senza record di eventi

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

Nota

Questi esempi non sono esempi completi. Mostrano dati rappresentativi derivanti da 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 come testo semplice.

{
  "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 i risultati dello strumento sotto forma di blocchi di contenuto Anthropic, che AgentCore Evaluations elimina.

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