克劳德特工 SDK
本页介绍如何检测 Claude Agent SDK 代理、如何识别跨度以及如何提取评估字段。
主题
对你的代理进行仪器
您可以使用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",
]
仪器化是设置可观测性的一个步骤。要导出遥测以进行评估，请在设置可观测性中完成完整设置。
如何识别跨度
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) 都在跨度上。有关更多信息，请参阅跨度、事件记录和遥测信号。
拆分遥测时， AgentCore 评估会从与每个跨度相关的事件记录中读取内容：
有关示例，请参阅包含事件记录的跨度示例。
如果未拆分遥测，则相同的内容将作为属性保留在跨度上：
有关示例，请参阅没有事件记录的跨度示例。
包含事件记录的示例
拆分遥测时，跨度带有识别属性，内容存在于相关的事件记录中。以下示例来自部署在亚马逊 Bedrock Runtime 上的 Claude Agent SDK 差旅计划代理。 AgentCore
这些示例不是完整的跨度。它们显示来自真实代理互动的代表性数据，为了便于阅读，省略了一些字段，长值被截断。
例
- 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) 将其标识为执行工具跨度；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 旅行计划代理。
这些示例不是完整的跨度。它们显示来自真实代理互动的代表性数据，为了便于阅读，省略了一些字段，长值被截断。
例
- 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 评估会将其解包。
{
"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"
}
}
