View a markdown version of this page

Claude Agent SDK - Amazon Grundgestein AgentCore
Instrumentieren Sie Ihren AgentenWie werden Spannweiten identifiziertWie werden Bewertungsfelder extrahiertBeispiel für Zeitspannen mit EreignisdatensätzenBeispiel für Bereiche ohne Ereignisdatensätze

Claude Agent SDK

Auf dieser Seite wird erklärt, wie ein Claude Agent SDK-Agent instrumentiert wird, wie Spans identifiziert werden und wie Bewertungsfelder extrahiert werden.

Topics

Instrumentieren Sie Ihren Agenten

Sie können einen Claude Agent SDK-Agenten mit der OpenInferenceInstrumentierungsbibliothek (openinference-instrumentation-claude-agent-sdk) instrumentieren. Diese Bibliothek sendet Telemetrie unter dem Bereichsnamen ausopeninference.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 ab.

Wie werden Spannweiten identifiziert

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

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.

Aus Ereignisaufzeichnungen

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 undbody.output. AgentCore Evaluationen entschlüsselt die inhaltlichen Blöcke der Anthropics im Tool-Ergebnis.

Beispiele finden Sie unter Beispielbereiche mit Ereignisdatensätzen.

Aus Span-Attributen

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 vontool.name, die Tool-Aufruf-ID von tool.idinput.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.

Beispiel für Zeitspannen mit Ereignisdatensätzen

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.

Beispiel
Invoke agent span

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

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

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.

Beispiel
Invoke agent span

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

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