# Strands Agents
本页介绍如何检测 Stran [ds Agents 代理](https://strandsagents.com/latest/)、如何识别跨度以及如何提取评估字段。
**主题**
+ [对你的代理进行仪器](#strands-instrument)
+ [如何识别跨度](#strands-span-identification)
+ [如何提取评估字段](#strands-extraction)
+ [来自事件记录](#strands-extraction-event-records)
+ [来自内联跨度事件](#strands-extraction-inline-events)
+ [包含事件记录的示例](#strands-examples-with)
+ [没有事件记录的示例跨度](#strands-examples-without)
## 对你的代理进行仪器
Strands Agents SDK 包含内置的遥测功能，不需要额外的仪器库。它在作用域名称`strands.telemetry.tracer`下生成跨度和事件记录。使用 AWS 发行版 OpenTelemetry (ADOT) 在 Amazon Bedrock R AgentCore untime 上部署时，运行时会注入`session.id`属性并自动导出跨度和事件记录。
**注意**
仪器化是设置可观测性的一个步骤。要导出遥测以进行评估，请在设置[可观](supported-frameworks.md#supported-frameworks-setup)测性中完成完整设置。
## 如何识别跨度
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 拆分遥测数据时，内容将存储在单独的事件记录中。如果未拆分遥测，则内容将作为内联事件保持在跨度上。有关更多信息，请参阅[跨度、事件记录和遥测信](supported-frameworks-telemetry.md)号。在这两种情况下，标识属性 (`gen_ai.operation.name`) 都在跨度上。
### 来自事件记录
拆分遥测时，该服务会从与每个跨度相关的事件记录中读取内容：
+ **用户提示**：来自代理输入消息 (`input.messages`)，带有用户角色的消息内容。
+ **代理响应**：来自代理输出消息 (`output.messages`)，带有助理角色的消息内容。
+ **工具调用**：来自执行工具跨度`gen_ai.tool.name`属性的工具名称。工具参数和结果来自该跨度的事件记录（`input`和`output`）。
有关示例，请参阅[包含事件记录的跨度示](#strands-examples-with)例。
### 来自内联跨度事件
如果不拆分遥测，则在行内跨度事件中传输相同的内容，而不是单独的事件记录：
+ **用户提示**：来自`gen_ai.user.message`事件，`content`属性。
+ **代理响应**：来自`gen_ai.choice`事件，`message`属性。
+ **工具调用**：来自跨度`gen_ai.tool.name`属性的工具名称。工具参数来自`gen_ai.tool.message`事件，结果来自`gen_ai.choice`事件。
有关示例，请参阅[没有事件记录的跨度示](#strands-examples-without)例。
## 包含事件记录的示例
拆分遥测时，跨度带有识别属性，内容存在于相关的事件记录中。以下示例来自部署在 Amazon Bedrock Runtime 上的 Strands 旅行计划代理。 AgentCore
**注意**
这些示例不是完整的跨度。它们显示来自真实代理互动的代表性数据，为了便于阅读，省略了一些字段，长值被截断。
**Example**
`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"
}
}
]
}
}
}
```
`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的旅行计划代理商。
**注意**
这些示例不是完整的跨度。它们显示来自真实代理互动的代表性数据，为了便于阅读，省略了一些字段，长值被截断。
**Example**
该`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"
}
}
]
}
```
该`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"
}
}
]
}
```