# Claude エージェント SDK
このページでは、[Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk/overview) エージェントを計測する方法、スパンの識別方法、評価フィールドの抽出方法について説明します。
**トピック**
+ [エージェントを計測する](#claude-agent-sdk-instrument)
+ [スパンの識別方法](#claude-agent-sdk-span-identification)
+ [評価フィールドの抽出方法](#claude-agent-sdk-extraction)
+ [イベントレコードから](#claude-agent-sdk-extraction-event-records)
+ [スパン属性から](#claude-agent-sdk-extraction-attributes)
+ [イベントレコードを含むスパンの例](#claude-agent-sdk-examples-with)
+ [イベントレコードのないスパンの例](#claude-agent-sdk-examples-without)
## エージェントを計測する
**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 つのステップです。評価のためにテレメトリをエクスポートするには、[「オブザーバビリティの設定](supported-frameworks.md#supported-frameworks-setup)」で完全なセットアップを完了します。
## スパンの識別方法
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`) はスパン上にあります。詳細については、[「スパン、イベントレコード、テレメトリシグナル](supported-frameworks-telemetry.md)」を参照してください。
### イベントレコードから
テレメトリが分割されると、AgentCore Evaluations は各スパンに相関するイベントレコードからコンテンツを読み取ります。
+ **ユーザープロンプト**と**エージェントのレスポンス**: エージェントスパンのイベントレコードの呼び出しから、 `body.input`および 。 `body.output`
+ **ツール呼び出し**: `tool.name` 属性からのツール名と実行ツールスパン`tool.id`の からのツール呼び出し ID。ツールの引数と結果は、 `body.input`と のスパンのイベントレコードから取得されます`body.output`。AgentCore Evaluations は、ツール結果で Anthropic コンテンツブロックをラップ解除します。
例については、[「イベントレコードを含むスパンの例](#claude-agent-sdk-examples-with)」を参照してください。
### スパン属性から
テレメトリが分割されていない場合、同じコンテンツは属性と同じスパンに残ります。
+ **ユーザープロンプト**と**エージェントのレスポンス**: `input.value` `output.value` 呼び出しエージェントのスパンとの間で。
+ **ツール呼び出し**: 実行ツールスパンの からのツール名`tool.name`、 からのツール呼び出し ID`output.value`、 からの`tool.id`引数`input.value`、および の結果。AgentCore Evaluations は、ツール結果で Anthropic コンテンツブロックをラップ解除します。
例については、[「イベントレコードのないスパンの例](#claude-agent-sdk-examples-without)」を参照してください。
## イベントレコードを含むスパンの例
テレメトリが分割されると、スパンは識別属性を保持し、コンテンツは相関イベントレコードに存在します。次の例は、Amazon Bedrock AgentCore ランタイムにデプロイされた Claude Agent SDK の旅行計画エージェントからのものです。
**注記**
これらの例は完全なスパンではありません。実際のエージェントインタラクションからの代表的なデータが表示され、読みやすいように一部のフィールドは省略され、長い値は切り捨てられます。
**Example**
`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 ..." }
]
}
}
}
```
`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 の旅行計画エージェントからのものです。
**注記**
これらの例は完全なスパンではありません。実際のエージェントインタラクションからの代表的なデータが表示され、読みやすいように一部のフィールドは省略され、長い値は切り捨てられます。
**Example**
`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"
}
}
```
`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"
}
}
```