本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 为评估设置 Strands Agents 遥测功能 AgentCore
本页介绍如何对 [ Strands Agents ](https://strandsagents.com/latest/) 代理进行仪器测量、如何识别跨度以及如何提取评估字段。
**主题**
+ [Python 代理支持 ](#strands-python)
+ [为您的代理人提供仪器 ](#strands-instrument)
+ [如何识别跨度 ](#strands-span-identification)
+ [如何提取评估字段 ](#strands-extraction)
+ [来自事件记录 ](#strands-extraction-event-records)
+ [来自内联跨度事件 ](#strands-extraction-inline-events)
+ [分体遥测中的示例跨度 ](#strands-examples-split)
+ [统一遥测中的示例跨度 ](#strands-examples-unified)
+ [TypeScript 代理支持 ](#strands-typescript)
+ [为您的代理人提供仪器 ](#strands-typescript-instrument)
+ [如何识别跨度 ](#strands-typescript-span-identification)
+ [如何提取评估字段 ](#strands-typescript-extraction)
+ [来自代理的示例跨度 TypeScript ](#strands-examples-typescript)
AgentCore 评估支持使用 Python SDK 和 SDK 构建的 Strands 代理。 TypeScript 两者在不同的范围名称下生成相同的跨度类型、标识属性和内容布局，因此评估服务以相同的方式读取它们。本页分别介绍每种语言：对于 Python，请参阅 [ Python 代理支持](#strands-python)；有关代理支持 TypeScript，请参阅[TypeScript 代理支持](#strands-typescript)。
## Python 代理支持
Python Strands 代理在作用域名称下生成跨度。`strands.telemetry.tracer`
### 为您的代理人提供仪器
Strands Agents SDK 包含内置遥测功能，不需要额外的仪器库。它以范围名称`strands.telemetry.tracer`生成跨度和事件记录。当使用 Amazon 发行版 OpenTelemetry (ADOT) 在 Amazon Bedrock R AgentCore untime 上部署时，运行时会注入该`session.id`属性并自动导出跨度和事件记录。
**注意**
仪器仪表是设置可观测性的一个步骤。要导出遥测数据进行评估，请在设置可观[测性中](supported-frameworks-telemetry.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` |
### 如何提取评估字段
对话内容的位置取决于遥测传送模式。使用分离式遥测，内容位于单独的事件记录中。使用统一的遥测技术，内容将作为附加事件保持在跨度内。有关更多信息，请参阅[遥测设置和交付](supported-frameworks-telemetry.md)。在两种模式下，识别属性 (`gen_ai.operation.name`) 都处于跨度内。
#### 来自事件记录
通过拆分遥测，该服务从与每个跨度相关的事件记录中读取内容：
+ **用户提示**：来自代理输入消息 (`input.messages`)，带有用户角色的消息内容。
+ **代理响应**：来自代理输出消息 (`output.messages`)，具有助理角色的消息内容。
+ **工具调用**：执行工具跨度上`gen_ai.tool.name`属性的工具名称。工具参数和结果来自该跨度的事件记录（`input`和`output`）。
有关更多信息，请参见分割遥测[中的跨度](#strands-examples-split)示例。
#### 来自内联跨度事件
使用统一的遥测技术，相同的内容将在内联跨度事件中传输，而不是单独的事件记录：
+ **用户提示**：来自`gen_ai.user.message`事件的`content`属性。
+ **代理响应**：来自`gen_ai.choice`事件的`message`属性。
+ **工具调用**：跨度上`gen_ai.tool.name`属性的工具名称。工具参数来自`gen_ai.tool.message`事件，结果来自`gen_ai.choice`事件。
有关更多信息，请参阅统一遥测[中的跨度](#strands-examples-unified)示例。
### 分体遥测中的跨度示例
使用分离式遥测，跨度携带识别属性，内容存在于相关的事件记录中。以下示例来自部署在亚马逊 Bedrock Runtime 上的 Python 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"
}
}
]
}
}
}
```
### 统一遥测中的示例跨度
使用统一的遥测技术，跨度的内联跨度事件中会传送相同的内容，没有单独的事件记录。以下示例来自 Python 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"
}
}
]
}
```
## TypeScript 代理支持
TypeScript Strands 代理在作用域名称下生成跨度。`strands-agents`它发出的跨度类型和内容布局与 Python 代理相同，因此评估服务以相同的方式读取它。
### 为您的代理人提供仪器
TypeScript Strands Agents SDK (`@strands-agents/sdk``>= 1.5.0`) 包含内置遥测功能，不需要额外的仪器库。当使用 Amazon 发行版 OpenTelemetry (ADOT) 在 Amazon Bedrock R AgentCore untime 上部署时，运行时会注入该`session.id`属性并自动导出跨度和事件记录。S TypeScript DK 在作用域名称`strands-agents`下生成跨度。
**注意**
仪器仪表是设置可观测性的一个步骤。要导出遥测数据进行评估，请在设置可观[测性中](supported-frameworks-telemetry.md#supported-frameworks-setup)完成完整设置。
### 如何识别跨度
跨度识别与 Python 代理相同。该`gen_ai.operation.name`属性对每个跨度进行分类。有关值和示例跨度名称，请参阅 [ Python 支持[如何识别跨度](#strands-span-identification)下的](#strands-python)如何识别跨度。
### 如何提取评估字段
字段提取与 Python 代理相同。对话内容以行内跨度事件（`gen_ai.user.message``gen_ai.choice`、和`gen_ai.tool.message`）形式传输。有关从何处读取每个字段，请参阅 [ Python 支持[下的](#strands-extraction-inline-events)来自内联跨度事件](#strands-python)。
### 来自代理的示例跨度 TypeScript
以下示例来自部署在亚马逊 Bedrock Runtime 上的 TypeScript Strands 旅行计划代理。 AgentCore
**注意**
这些例子并不完整。它们显示来自真实代理交互的代表性数据，为了便于阅读，省略了一些字段并截断了长值。
**Example**
`gen_ai.operation.name`属性 (`invoke_agent`) 将其标识为调用代理跨度，并`gen_ai.agent.tools`列出可供代理使用的工具。该`gen_ai.user.message`事件保存用户提示，该`gen_ai.choice`事件保存代理响应。
```
{
"traceId": "6a6bc695459e41aa14a172bb41d3246d",
"spanId": "c2c44e69bdab6ef1",
"parentSpanId": "f18d96d107e793ba",
"name": "invoke_agent Strands Agent",
"kind": "INTERNAL",
"scope": {
"name": "strands-agents",
"version": ""
},
"attributes": {
"gen_ai.operation.name": "invoke_agent",
"gen_ai.agent.name": "Strands Agent",
"gen_ai.system": "strands-agents",
"gen_ai.request.model": "global.anthropic.claude-sonnet-4-5-20250929-v1:0",
"gen_ai.agent.tools": "[\"search_flights\", \"book_flight\", \"search_hotels\", \"book_hotel\", \"search_activities\", \"book_activity\"]",
"session.id": "sea-nyc-trip-2-turns"
},
"events": [
{
"name": "gen_ai.user.message",
"attributes": {
"content": "[{\"text\": \"Hey, how can you help me\"}]"
}
},
{
"name": "gen_ai.choice",
"attributes": {
"message": "Hello! I'm your travel planning assistant, and I can help you with the following: ..."
}
}
]
}
```
`gen_ai.operation.name`属性 (`execute_tool`) 将其标识为执行工具跨度；`gen_ai.tool.name`包含工具名称。该`gen_ai.tool.message`事件保存工具参数，该`gen_ai.choice`事件保存工具结果。
```
{
"traceId": "6a6bc69e6eaa1e994481bef349f4c72e",
"spanId": "4227ac5525f22dd2",
"parentSpanId": "8a989e0dbb9dc22f",
"name": "execute_tool search_flights",
"kind": "INTERNAL",
"scope": {
"name": "strands-agents",
"version": ""
},
"attributes": {
"gen_ai.operation.name": "execute_tool",
"gen_ai.tool.name": "search_flights",
"gen_ai.tool.call.id": "tooluse_AoP0OTnq2YcOZDvY7ldSUQ",
"gen_ai.tool.status": "success",
"session.id": "sea-nyc-trip-2-turns"
},
"events": [
{
"name": "gen_ai.tool.message",
"attributes": {
"content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
"role": "tool",
"id": "tooluse_AoP0OTnq2YcOZDvY7ldSUQ"
}
},
{
"name": "gen_ai.choice",
"attributes": {
"message": "[{\"text\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\"}]",
"id": "tooluse_AoP0OTnq2YcOZDvY7ldSUQ"
}
}
]
}
```