本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
克劳德特工 SDK
本页介绍如何检测 Claude Ag ent SDK 代理、如何识别跨度以及如何提取评估字段。
主题
为您的代理人提供仪器
您可以使用仪器库 (openinference-instrumentation-claude-agent-sdk) 对 Claude Agent SDK 代理进行OpenInference检测。该库以范围名称发射遥测数据openinference.instrumentation.claude_agent_sdk，亚马逊基岩 AgentCore 评估读取了该名称。
当您的代理使用 AWS 发行版 OpenTelemetry (ADOT) 运行时，例如在 Amazon Bedrock AgentCore 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 span 本身上传输。
Claude Agent SDK 生成干净的纯文本代理输入和输出，因此用户提示和代理响应无需特殊解析。但是，工具结果以人类内容块的形式出现[{"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"
}
}
