View a markdown version of this page

Claude エージェント SDK - Amazon Bedrock AgentCore
エージェントを計測するスパンの識別方法評価フィールドの抽出方法イベントレコードを含むスパンの例イベントレコードのないスパンの例

Claude エージェント SDK

このページでは、Claude Agent SDK エージェントを計測する方法、スパンの識別方法、評価フィールドの抽出方法について説明します。

トピック

エージェントを計測する

OpenInference 計測ライブラリ () を使用して Claude Agent SDK エージェントを計測できますopeninference-instrumentation-claude-agent-sdk。このライブラリはopeninference.instrumentation.claude_agent_sdk、Amazon Bedrock AgentCore Evaluations が読み取るスコープ名 でテレメトリを出力します。

Amazon Bedrock AgentCore ランタイムなど、エージェントが AWS Distro for OpenTelemetry (ADOT) で実行されている場合、明示的な計測コードを追加する必要はありません。計測ライブラリをプロジェクトの依存関係に追加するだけで十分です。ADOT は起動時に検出し、自動的にアクティブ化します。

計測ライブラリを依存関係に追加します。

注記

バージョン 0.1.3 以降を使用します。これは、評価サービスでテストされた最も古いバージョンです。

requirements.txt:

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

pyproject.toml:

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

計測は、オブザーバビリティを設定する 1 つのステップです。評価のためにテレメトリをエクスポートするには、「オブザーバビリティの設定」で完全なセットアップを完了します。

スパンの識別方法

Claude Agent SDK は OpenInference 規則で計測されるため、AgentCore Evaluations は openinference.span.kind 属性を使用してスパンを分類します。

スパンタイプ 属性の識別

エージェントを呼び出す

openinference.span.kind = AGENT

実行ツール

openinference.span.kind = TOOL

Claude エージェント SDK は AGENTと TOOL スパンのみを出力します。個別の推論 (LLM) スパンは出力しません。モデルメタデータ (モデル名、トークンの使用) とエージェントのレスポンスは、AGENTスパン自体で伝送されます。

評価フィールドの抽出方法

Claude Agent SDK はクリーンなプレーンテキストのエージェントの入出力を生成するため、ユーザープロンプトとエージェントのレスポンスに特別な解析は必要ありません。ただし、ツールの結果は Anthropic コンテンツブロックとして 形式で到着します[{"type": "text", "text": "…​"}]。AgentCore Evaluations は、これらのブロックをラップ解除し、テキストを連結します。

このコンテンツの場所は、テレメトリの収集方法によって異なります。どちらの場合も、識別属性 (openinference.span.kind) はスパン上にあります。詳細については、「スパン、イベントレコード、テレメトリシグナル」を参照してください。

イベントレコードから

テレメトリが分割されると、AgentCore Evaluations は各スパンに相関するイベントレコードからコンテンツを読み取ります。

  • ユーザープロンプトとエージェントのレスポンス: エージェントスパンのイベントレコードの呼び出しから、 body.inputおよび 。 body.output

  • ツール呼び出し: tool.name 属性からのツール名と実行ツールスパンtool.idの からのツール呼び出し ID。ツールの引数と結果は、 body.inputと のスパンのイベントレコードから取得されますbody.output。AgentCore Evaluations は、ツール結果で Anthropic コンテンツブロックをラップ解除します。

例については、「イベントレコードを含むスパンの例」を参照してください。

スパン属性から

テレメトリが分割されていない場合、同じコンテンツは属性と同じスパンに残ります。

  • ユーザープロンプトとエージェントのレスポンス: input.value output.value 呼び出しエージェントのスパンとの間で。

  • ツール呼び出し: 実行ツールスパンの からのツール名tool.name、 からのツール呼び出し IDoutput.value、 からのtool.id引数input.value、および の結果。AgentCore Evaluations は、ツール結果で Anthropic コンテンツブロックをラップ解除します。

例については、「イベントレコードのないスパンの例」を参照してください。

イベントレコードを含むスパンの例

テレメトリが分割されると、スパンは識別属性を保持し、コンテンツは相関イベントレコードに存在します。次の例は、Amazon Bedrock AgentCore ランタイムにデプロイされた Claude Agent SDK の旅行計画エージェントからのものです。

注記

これらの例は完全なスパンではありません。実際のエージェントインタラクションからの代表的なデータが表示され、読みやすいように一部のフィールドは省略され、長い値は切り捨てられます。

例
Invoke agent span

openinference.span.kind 属性 (AGENT) は、これを呼び出しエージェントのスパンとして識別します。スパンはモデルメタデータを保持し、会話コンテンツは相関イベントレコードに存在します。

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

openinference.span.kind 属性 (TOOL) は、これを実行ツールスパンとして識別します。 はツール名とツール呼び出し ID tool.nameを保持tool.idします。ツールの結果は、相関イベントレコードに Anthropic コンテンツブロックとして残り、AgentCore Evaluations はラップを解除します。

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

イベントレコードのないスパンの例

テレメトリが分割されていない場合、同じコンテンツはスパン属性に残り、個別のイベントレコードは生成されません。次の例は、Claude Agent SDK の旅行計画エージェントからのものです。

注記

これらの例は完全なスパンではありません。実際のエージェントインタラクションからの代表的なデータが表示され、読みやすいように一部のフィールドは省略され、長い値は切り捨てられます。

例
Invoke agent span

input.value 属性はユーザープロンプトを保持し、 output.value 属性はエージェントレスポンスをプレーンテキストとして保持します。

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

input.value 属性はツール引数を保持し、 output.value 属性はツール結果を Anthropic コンテンツブロックとして保持し、AgentCore Evaluations はラップを解除します。

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