# Claude 代理程式開發套件
此頁面說明如何檢測 [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`。此程式庫會在 Amazon Bedrock AgentCore Evaluations `openinference.instrumentation.claude_agent_sdk`讀取的範圍名稱 下發出遙測。
當您的代理程式使用 AWS Distro for OpenTelemetry (ADOT) 執行時，例如在 Amazon Bedrock AgentCore 執行期，您不需要新增明確的檢測程式碼。將檢測程式庫新增至專案的相依性已足夠。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",
]
```
**注意**
檢測是設定可觀測性的一個步驟。若要匯出遙測資料進行評估，請完成設定[可觀測性中的完整設定](supported-frameworks.md#supported-frameworks-setup)。
## 如何識別跨度
Claude Agent SDK 使用 OpenInference 慣例進行檢測，因此 AgentCore Evaluations 會使用 `openinference.span.kind` 屬性對範圍進行分類。
| 跨度類型 | 識別屬性 |
| --- | --- |
| 叫用代理程式 | `openinference.span.kind` = `AGENT` |
| 執行工具 | `openinference.span.kind` = `TOOL` |
Claude Agent 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)。
### 從跨度屬性
未分割遙測時，相同的內容會保留在跨度上做為屬性：
+ **使用者提示**和**客服人員回應**：調用客服人員範圍`output.value`上的 `input.value`和 。
+ **工具呼叫**：執行工具範圍上來自 的工具名稱`tool.name`、來自 的工具呼叫 ID`input.value`、來自 的`tool.id`引數`output.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`) 將此識別為執行工具範圍； `tool.name`會保留工具名稱和`tool.id`工具呼叫 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"
}
}
```