Strands Agents
本页介绍如何检测 Stran ds Agents 代理、如何识别跨度以及如何提取评估字段。
主题
对你的代理进行仪器
Strands Agents SDK 包含内置的遥测功能，不需要额外的仪器库。它在作用域名称strands.telemetry.tracer下生成跨度和事件记录。使用 AWS 发行版 OpenTelemetry (ADOT) 在 Amazon Bedrock R AgentCore untime 上部署时，运行时会注入session.id属性并自动导出跨度和事件记录。
仪器化是设置可观测性的一个步骤。要导出遥测以进行评估，请在设置可观测性中完成完整设置。
如何识别跨度
Strands 在每个跨度上设置gen_ai.operation.name属性。评估服务使用此属性对跨度进行分类：
| 跨度类型 |
识别属性 |
跨度名称示例 |
|
调用代理
|
gen_ai.operation.name = invoke_agent
|
invoke_agent TravelAgent
|
|
执行工具
|
gen_ai.operation.name = execute_tool
|
execute_tool search_flights
|
|
推理
|
gen_ai.operation.name = chat
|
chat
|
如何提取评估字段
对话内容的位置取决于遥测数据的收集方式。当 ADOT 拆分遥测数据时，内容将存储在单独的事件记录中。如果未拆分遥测，则内容将作为内联事件保持在跨度上。有关更多信息，请参阅跨度、事件记录和遥测信号。在这两种情况下，标识属性 (gen_ai.operation.name) 都在跨度上。
来自事件记录
拆分遥测时，该服务会从与每个跨度相关的事件记录中读取内容：
-
用户提示：来自代理输入消息 (input.messages)，带有用户角色的消息内容。
-
代理响应：来自代理输出消息 (output.messages)，带有助理角色的消息内容。
-
工具调用：来自执行工具跨度gen_ai.tool.name属性的工具名称。工具参数和结果来自该跨度的事件记录（input和output）。
有关示例，请参阅包含事件记录的跨度示例。
来自内联跨度事件
如果不拆分遥测，则在行内跨度事件中传输相同的内容，而不是单独的事件记录：
-
用户提示：来自gen_ai.user.message事件，content属性。
-
代理响应：来自gen_ai.choice事件，message属性。
-
工具调用：来自跨度gen_ai.tool.name属性的工具名称。工具参数来自gen_ai.tool.message事件，结果来自gen_ai.choice事件。
有关示例，请参阅没有事件记录的跨度示例。
包含事件记录的示例
拆分遥测时，跨度带有识别属性，内容存在于相关的事件记录中。以下示例来自部署在 Amazon Bedrock Runtime 上的 Strands 旅行计划代理。 AgentCore
这些示例不是完整的跨度。它们显示来自真实代理互动的代表性数据，为了便于阅读，省略了一些字段，长值被截断。
例
- Invoke agent span
-
gen_ai.operation.name属性 (invoke_agent) 将其标识为调用代理跨度。该gen_ai.agent.tools属性列出了代理可用的工具。
{
"traceId": "69e9cc4771d7cabe0d8e8cea33b6b338",
"spanId": "d24936b8989b6d42",
"parentSpanId": "0ff3498548044e4b",
"name": "invoke_agent TravelAgent",
"kind": "INTERNAL",
"scope": {
"name": "strands.telemetry.tracer",
"version": ""
},
"startTimeUnixNano": 1776929864011990383,
"endTimeUnixNano": 1776929869634304466,
"durationNano": 5622314083,
"attributes": {
"gen_ai.operation.name": "invoke_agent",
"gen_ai.system": "strands-agents",
"gen_ai.agent.name": "TravelAgent",
"gen_ai.request.model": "us.anthropic.claude-sonnet-4-20250514-v1:0",
"gen_ai.usage.input_tokens": 983,
"gen_ai.usage.output_tokens": 232,
"gen_ai.usage.total_tokens": 1215,
"gen_ai.agent.tools": "[\"search_flights\", \"book_flight\", \"search_hotels\", \"book_hotel\", \"search_activities\", \"book_activity\"]",
"session.id": "sea-nyc-trip-2-turns-adot_v17-20260423003743"
},
"status": {
"code": "OK"
}
}
关联的事件记录包含对话内容。用户提示是中的用户角色消息input.messages，代理响应是中的助理角色消息。output.messages
{
"spanId": "d24936b8989b6d42",
"traceId": "69e9cc4771d7cabe0d8e8cea33b6b338",
"scope": {
"name": "strands.telemetry.tracer"
},
"body": {
"input": {
"messages": [
{
"role": "user",
"content": "Hey, how can you help me"
}
]
},
"output": {
"messages": [
{
"role": "assistant",
"content": {
"message": "Hi there! I'm your travel planning assistant ...",
"finish_reason": "end_turn"
}
}
]
}
}
}
- Execute tool span
-
gen_ai.operation.name属性 (execute_tool) 将其标识为执行工具跨度。该gen_ai.tool.name属性包含工具名称。
{
"traceId": "69e9cc4d132b180909ba49f613f273dd",
"spanId": "fff785ce12d6fda8",
"parentSpanId": "96915bf5ecc78743",
"name": "execute_tool search_flights",
"kind": "INTERNAL",
"scope": {
"name": "strands.telemetry.tracer",
"version": ""
},
"startTimeUnixNano": 1776929872258292842,
"endTimeUnixNano": 1776929872259611427,
"durationNano": 1318585,
"attributes": {
"gen_ai.operation.name": "execute_tool",
"gen_ai.tool.name": "search_flights",
"gen_ai.tool.call.id": "tooluse_hiWwdtThuD67G5cK8cp5mj",
"gen_ai.tool.status": "success",
"gen_ai.tool.description": "Search for available flights between cities.",
"session.id": "sea-nyc-trip-2-turns-adot_v17-20260423003743"
},
"status": {
"code": "OK"
}
}
关联的事件记录包含工具输入（参数）和输出（结果）。
{
"spanId": "fff785ce12d6fda8",
"traceId": "69e9cc4d132b180909ba49f613f273dd",
"scope": {
"name": "strands.telemetry.tracer"
},
"body": {
"input": {
"messages": [
{
"role": "tool",
"content": {
"content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
"role": "tool",
"id": "tooluse_hiWwdtThuD67G5cK8cp5mj"
}
}
]
},
"output": {
"messages": [
{
"role": "assistant",
"content": {
"message": "[{\"text\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\"}]",
"id": "tooluse_hiWwdtThuD67G5cK8cp5mj"
}
}
]
}
}
}
没有事件记录的示例跨度
如果不拆分遥测，则在跨度上的内联跨度事件中传输相同的内容，没有单独的事件记录。以下示例来自Strands的旅行计划代理商。
这些示例不是完整的跨度。它们显示来自真实代理互动的代表性数据，为了便于阅读，省略了一些字段，长值被截断。
例
- Invoke agent span
-
该gen_ai.user.message事件保存用户提示，gen_ai.choice事件保存代理响应。
{
"traceId": "69e9cc4771d7cabe0d8e8cea33b6b338",
"spanId": "d2ee0e4765cc773e",
"name": "invoke_agent TravelAgent",
"kind": "INTERNAL",
"scope": {
"name": "strands.telemetry.tracer"
},
"attributes": {
"gen_ai.operation.name": "invoke_agent",
"gen_ai.agent.name": "TravelAgent",
"session.id": "sea-nyc-trip-2-turns-unified"
},
"events": [
{
"name": "gen_ai.user.message",
"attributes": {
"content": "[{\"text\": \"Hey, how can you help me\"}]"
}
},
{
"name": "gen_ai.choice",
"attributes": {
"message": "Hi there! I'm your travel planning assistant ...",
"finish_reason": "end_turn"
}
}
]
}
- Execute tool span
-
该gen_ai.tool.message事件保存工具参数，gen_ai.choice事件保存工具结果。
{
"traceId": "69e9cc4d132b180909ba49f613f273dd",
"spanId": "0a988e27758ebb53",
"name": "execute_tool search_flights",
"kind": "INTERNAL",
"scope": {
"name": "strands.telemetry.tracer"
},
"attributes": {
"gen_ai.operation.name": "execute_tool",
"gen_ai.tool.name": "search_flights",
"gen_ai.tool.call.id": "tooluse_JuGterOaZfQV2c55Rp3S7C",
"gen_ai.tool.status": "success",
"session.id": "sea-nyc-trip-2-turns-unified"
},
"events": [
{
"name": "gen_ai.tool.message",
"attributes": {
"content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
"role": "tool",
"id": "tooluse_JuGterOaZfQV2c55Rp3S7C"
}
},
{
"name": "gen_ai.choice",
"attributes": {
"message": "[{\"text\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\"}]",
"id": "tooluse_JuGterOaZfQV2c55Rp3S7C"
}
}
]
}
