为评估设置 Strands Agents 遥测功能 AgentCore

本页介绍如何对 Strands Agents 代理进行仪器测量、如何识别跨度以及如何提取评估字段。

主题

Python 代理支持
TypeScript 代理支持

AgentCore 评估支持使用 Python SDK 和 SDK 构建的 Strands 代理。 TypeScript 两者在不同的范围名称下生成相同的跨度类型、标识属性和内容布局，因此评估服务以相同的方式读取它们。本页分别介绍每种语言：对于 Python，请参阅 Python 代理支持；有关代理支持 TypeScript，请参阅TypeScript 代理支持。

Python 代理支持

Python Strands 代理在作用域名称下生成跨度。strands.telemetry.tracer

为您的代理人提供仪器

Strands Agents SDK 包含内置遥测功能，不需要额外的仪器库。它以范围名称strands.telemetry.tracer生成跨度和事件记录。当使用 Amazon 发行版 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`

如何提取评估字段

对话内容的位置取决于遥测传送模式。使用分离式遥测，内容位于单独的事件记录中。使用统一的遥测技术，内容将作为附加事件保持在跨度内。有关更多信息，请参阅遥测设置和交付。在两种模式下，识别属性 (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事件。

有关更多信息，请参阅统一遥测中的跨度示例。

分体遥测中的跨度示例

使用分离式遥测，跨度携带识别属性，内容存在于相关的事件记录中。以下示例来自部署在亚马逊 Bedrock Runtime 上的 Python 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"
          }
        }
      ]
    }
  }
}

统一遥测中的示例跨度

使用统一的遥测技术，跨度的内联跨度事件中会传送相同的内容，没有单独的事件记录。以下示例来自 Python 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"
      }
    }
  ]
}

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下生成跨度。

注意

仪器仪表是设置可观测性的一个步骤。要导出遥测数据进行评估，请在设置可观测性中完成完整设置。

如何识别跨度

跨度识别与 Python 代理相同。该gen_ai.operation.name属性对每个跨度进行分类。有关值和示例跨度名称，请参阅 Python 支持如何识别跨度下的如何识别跨度。

如何提取评估字段

字段提取与 Python 代理相同。对话内容以行内跨度事件（gen_ai.user.messagegen_ai.choice、和gen_ai.tool.message）形式传输。有关从何处读取每个字段，请参阅 Python 支持下的来自内联跨度事件。

来自代理的示例跨度 TypeScript

以下示例来自部署在亚马逊 Bedrock Runtime 上的 TypeScript Strands 旅行计划代理。 AgentCore

注意

这些例子并不完整。它们显示来自真实代理交互的代表性数据，为了便于阅读，省略了一些字段并截断了长值。

例

Invoke agent span

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: ..."
      }
    }
  ]
}

Execute tool span

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"
      }
    }
  ]
}

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

支持的框架

LangGraph