# 克劳德特工 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**插桩库 (`openinference-instrumentation-claude-agent-sdk`) 对 Claude Agent SDK 代理进行检测。该库以作用域名称发射遥测数据，Amazon Bedrock AgentCore 评估读取该名称`openinference.instrumentation.claude_agent_sdk`。
当您的代理与 AWS Distro for OpenTelemetry (ADOT) 一起 AgentCore 运行时，例如在 Amazon Bedrock Runtime 上，您无需添加显式的检测代码。将仪器库添加到项目的依赖项中就足够了。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 评估使用该属性对跨度进行分类。`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 评估会解开这些方块的包装，并连接它们的文本。
这些内容的位置取决于遥测数据的收集方式。在这两种情况下，标识属性 (`openinference.span.kind`) 都在跨度上。有关更多信息，请参阅[跨度、事件记录和遥测信](supported-frameworks-telemetry.md)号。
### 来自事件记录
拆分遥测时， AgentCore 评估会从与每个跨度相关的事件记录中读取内容：
+ **用户提示**和**代理响应**：来自调用代理跨度的事件记录，在`body.input`和中`body.output`。
+ **工具调用**：`tool.name`属性的工具名称和执行工具跨度`tool.id`上的工具调用 ID。工具参数和结果来自该跨度的事件记录，位于`body.input`和中`body.output`。 AgentCore 评估会解开工具结果中的 Anthropic 内容块。
有关示例，请参阅[包含事件记录的跨度示](#claude-agent-sdk-examples-with)例。
### 来自跨度属性
如果未拆分遥测，则相同的内容将作为属性保留在跨度上：
+ **用户提示**和**代理响应**：从`input.value`和`output.value`在调用代理跨度上。
+ **工具调用**：执行工具跨度上的工具名称`tool.id`、来自的工具调用 ID `input.value` `output.value`、来自的参数和来自的结果。`tool.name` AgentCore 评估会解开工具结果中的 Anthropic 内容块。
有关示例，请参阅[没有事件记录的跨度示](#claude-agent-sdk-examples-without)例。
## 包含事件记录的示例
拆分遥测时，跨度带有识别属性，内容存在于相关的事件记录中。以下示例来自部署在亚马逊 Bedrock Runtime 上的 Claude Agent SDK 差旅计划代理。 AgentCore
**注意**
这些示例不是完整的跨度。它们显示来自真实代理互动的代表性数据，为了便于阅读，省略了一些字段，长值被截断。
**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 评估会将其解包。
```
{
"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 评估会将其解包。
```
{
"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"
}
}
```