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

Auf dieser Seite wird erklärt, wie ein [Claude Agent SDK-Agent](https://docs.claude.com/en/api/agent-sdk/overview) instrumentiert wird, wie Spans identifiziert werden und wie Bewertungsfelder extrahiert werden.

 **Topics** 
+  [Instrumentieren Sie Ihren Agenten](#claude-agent-sdk-instrument) 
+  [Wie werden Spannweiten identifiziert](#claude-agent-sdk-span-identification) 
+  [Wie werden Bewertungsfelder extrahiert](#claude-agent-sdk-extraction) 
  +  [Aus Ereignisaufzeichnungen](#claude-agent-sdk-extraction-event-records) 
  +  [Aus Span-Attributen](#claude-agent-sdk-extraction-attributes) 
+  [Beispiel für Spans mit Ereignisdatensätzen](#claude-agent-sdk-examples-with) 
+  [Beispiel für Spans ohne Ereignisdatensätze](#claude-agent-sdk-examples-without) 

## Instrumentieren Sie Ihren Agenten
<a name="claude-agent-sdk-instrument"></a>

Sie können einen Claude Agent SDK-Agenten mit der **OpenInference**Instrumentierungsbibliothek (`openinference-instrumentation-claude-agent-sdk`) instrumentieren. Diese Bibliothek sendet Telemetrie unter dem Bereichsnamen aus`openinference.instrumentation.claude_agent_sdk`, den Amazon Bedrock AgentCore Evaluations liest.

Wenn Ihr Agent mit AWS Distro for OpenTelemetry (ADOT) ausgeführt wird, z. B. auf Amazon Bedrock AgentCore Runtime, müssen Sie keinen expliziten Instrumentierungscode hinzufügen. Es reicht aus, die Instrumentierungsbibliothek zu den Abhängigkeiten Ihres Projekts hinzuzufügen. ADOT erkennt es beim Start und aktiviert es automatisch.

Fügen Sie die Instrumentierungsbibliothek zu Ihren Abhängigkeiten hinzu.

**Anmerkung**  
Verwenden Sie Version `0.1.3` oder höher. Dies ist die früheste Version, die mit dem Evaluierungsservice getestet wurde.

 `requirements.txt`:

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

 `pyproject.toml`:

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

**Anmerkung**  
Die Instrumentierung ist ein Schritt zur Schaffung der Beobachtbarkeit. Um Telemetrie zur Auswertung zu exportieren, schließen Sie die vollständigen Einstellungen unter Beobachtbarkeit [einrichten](supported-frameworks.md#supported-frameworks-setup) ab.

## Wie werden Spannweiten identifiziert
<a name="claude-agent-sdk-span-identification"></a>

Das Claude Agent SDK ist mit dieser OpenInference Konvention ausgestattet, sodass AgentCore Evaluations die Spans anhand des Attributs klassifiziert. `openinference.span.kind`


| Art der Spanne | Identifizierendes Attribut | 
| --- | --- | 
| Agent aufrufen |  `openinference.span.kind` = `AGENT`  | 
| Tool ausführen |  `openinference.span.kind` = `TOOL`  | 

Das Claude Agent SDK sendet nur `TOOL` Spans `AGENT` und gibt keine separaten Inference () `LLM` -Spans aus. Die Modell-Metadaten (Modellname, Token-Verwendung) und die Antwort des Agenten werden im Span selbst übernommen. `AGENT`

## Wie werden Bewertungsfelder extrahiert
<a name="claude-agent-sdk-extraction"></a>

Das Claude Agent SDK erzeugt saubere Agenteneingabe und -ausgabe im Klartext, sodass die Benutzeraufforderung und die Antwort des Agenten keine spezielle Analyse erfordern. Die Werkzeugergebnisse werden jedoch als anthropische Inhaltsblöcke im Formular angezeigt. `[{"type": "text", "text": "…​"}]` AgentCore Evaluations entpackt diese Blöcke und verkettet ihren Text.

Der Speicherort dieser Inhalte hängt davon ab, wie die Telemetriedaten erfasst wurden. Das identifizierende Attribut (`openinference.span.kind`) befindet sich in beiden Fällen auf der Spanne. Weitere Informationen finden Sie unter [Spans, Ereignisdatensätze und Telemetriesignale](supported-frameworks-telemetry.md).

### Aus Ereignisaufzeichnungen
<a name="claude-agent-sdk-extraction-event-records"></a>

Wenn die Telemetrie aufgeteilt wird, liest AgentCore Evaluations Inhalte aus den Ereignisdatensätzen, die den einzelnen Bereichen zugeordnet sind:
+  **Benutzeraufforderung** und **Antwort des Agenten**: aus dem Ereignisdatensatz des Invoke Agent Span, in und. `body.input` `body.output`
+  **Werkzeugaufruf**: der Werkzeugname aus dem `tool.name` Attribut und die Tool-Aufruf-ID aus `tool.id` dem Bereich „Tool ausführen“. Die Werkzeugargumente und das Ergebnis stammen aus dem Ereignisdatensatz dieser Spanne, in `body.input` und`body.output`. AgentCore Evaluationen entschlüsselt die inhaltlichen Blöcke der Anthropics im Tool-Ergebnis.

Beispiele finden Sie unter [Beispielbereiche mit Ereignisdatensätzen.](#claude-agent-sdk-examples-with)

### Aus Span-Attributen
<a name="claude-agent-sdk-extraction-attributes"></a>

Wenn die Telemetrie nicht aufgeteilt wird, verbleibt derselbe Inhalt als Attribute im Bereich:
+  **Benutzeraufforderung** und **Agentenantwort**: von `input.value` und nach `output.value` dem Agentenaufruf.
+  **Werkzeugaufruf**: der Werkzeugname von`tool.name`, die Tool-Aufruf-ID von `tool.id``input.value`, die Argumente von und das Ergebnis von `output.value` im Bereich „Tool ausführen“. AgentCore Evaluationen entschlüsselt die inhaltlichen Blöcke von Anthropic im Tool-Ergebnis.

Beispiele finden Sie unter [Beispiel für Zeitspannen ohne Ereignisdatensätze](#claude-agent-sdk-examples-without).

## Beispiel für Zeitspannen mit Ereignisdatensätzen
<a name="claude-agent-sdk-examples-with"></a>

Wenn die Telemetrie aufgeteilt wird, enthält die Spanne die identifizierenden Attribute und der Inhalt befindet sich in einem korrelierten Ereignisdatensatz. Die folgenden Beispiele stammen von einem Reiseplanungsagenten des Claude Agent SDK, der auf Amazon AgentCore Bedrock Runtime eingesetzt wurde.

**Anmerkung**  
Bei diesen Beispielen handelt es sich nicht um vollständige Zeitspannen. Sie zeigen repräsentative Daten aus einer echten Agenteninteraktion, wobei einige Felder weggelassen und lange Werte aus Gründen der Lesbarkeit gekürzt wurden.

**Example**  
Das `openinference.span.kind` Attribut (`AGENT`) identifiziert dies als eine Spanne für den Aufruf-Agenten. Der Bereich enthält die Modellmetadaten; der Inhalt der Konversation befindet sich im korrelierten Ereignisdatensatz.  

```
{
  "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 ..." }
      ]
    }
  }
}
```
Das `openinference.span.kind` Attribut (`TOOL`) identifiziert dies als Span für das Ausführen eines Tools. Es `tool.name` enthält den Namen des Tools und `tool.id` die Aufruf-ID des Tools. Das Werkzeugergebnis befindet sich im korrelierten Ereignisdatensatz als anthropische Inhaltsblöcke, die von AgentCore Evaluations entpackt werden.  

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

## Beispiel für Bereiche ohne Ereignisdatensätze
<a name="claude-agent-sdk-examples-without"></a>

Wenn die Telemetrie nicht aufgeteilt wird, verbleibt derselbe Inhalt in den Span-Attributen und es wird kein separater Ereignisdatensatz erstellt. Die folgenden Beispiele stammen von einem Reiseplanungsbüro von Claude Agent SDK.

**Anmerkung**  
Bei diesen Beispielen handelt es sich nicht um vollständige Zeitspannen. Sie zeigen repräsentative Daten aus einer echten Agenteninteraktion, wobei einige Felder weggelassen und lange Werte aus Gründen der Lesbarkeit gekürzt wurden.

**Example**  
Das `input.value` Attribut enthält die Benutzeraufforderung und das `output.value` Attribut die Antwort des Agenten, beide als Klartext.  

```
{
  "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"
  }
}
```
Das `input.value` Attribut enthält die Werkzeugargumente, und das `output.value` Attribut enthält das Werkzeugergebnis in Form von anthropischen Inhaltsblöcken, die von AgentCore Evaluations entpackt werden.  

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