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

Questa pagina spiega come strumentare un [agente SDK di Claude Agent](https://docs.claude.com/en/api/agent-sdk/overview), come vengono identificati gli intervalli e come vengono estratti i campi di valutazione.

 **Argomenti** 
+  [Strumenta il tuo agente](#claude-agent-sdk-instrument) 
+  [Come vengono identificate le campate](#claude-agent-sdk-span-identification) 
+  [Come vengono estratti i campi di valutazione](#claude-agent-sdk-extraction) 
  +  [Dai registri degli eventi](#claude-agent-sdk-extraction-event-records) 
  +  [Dagli attributi span](#claude-agent-sdk-extraction-attributes) 
+  [L'esempio si estende ai record degli eventi](#claude-agent-sdk-examples-with) 
+  [Esempio di intervalli senza record di eventi](#claude-agent-sdk-examples-without) 

## Strumenta il tuo agente
<a name="claude-agent-sdk-instrument"></a>

Puoi strumentare un agente SDK di Claude Agent con la libreria di **OpenInference**strumentazione (). `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à.](supported-frameworks.md#supported-frameworks-setup)

## Come vengono identificati gli intervalli
<a name="claude-agent-sdk-span-identification"></a>

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
<a name="claude-agent-sdk-extraction"></a>

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](supported-frameworks-telemetry.md).

### Dai registri degli eventi
<a name="claude-agent-sdk-extraction-event-records"></a>

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.name`attributo 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](#claude-agent-sdk-examples-with) with event records.

### Dagli attributi span
<a name="claude-agent-sdk-extraction-attributes"></a>

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 da`tool.name`, l'ID della chiamata allo strumento da`tool.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](#claude-agent-sdk-examples-without) without event records.

## L'esempio si estende ai record degli eventi
<a name="claude-agent-sdk-examples-with"></a>

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

**Example**  
L'`openinference.span.kind`attributo (`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 ..." }
      ]
    }
  }
}
```
L'`openinference.span.kind`attributo (`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
<a name="claude-agent-sdk-examples-without"></a>

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

**Example**  
L'`input.value`attributo contiene il prompt dell'utente e l'`output.value`attributo 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"
  }
}
```
L'`input.value`attributo contiene gli argomenti dello strumento e l'`output.value`attributo 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"
  }
}
```