View a markdown version of this page

通用框架支持 - Amazon Bedrock AgentCore
支持的惯例如何识别跨度如何提取评估字段配置要求
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

通用框架支持

亚马逊基岩 AgentCore 评估通过两个开放标准来读取遥测数据： OpenTelemetry 生成式 AI 语义约定和语义约定。 OpenInference 除了在本节中有自己的页面的框架外，该服务还支持任何按照这两种惯例之一发出遥测信号的代理。这是通用框架支持。

当您使用本节中没有页面的框架进行构建时，或者当您为自定义代理编写自己的工具时，请使用通用框架支持。配置您的仪器以发出此页面上描述的范围名称、跨度属性和标识属性，该服务使用与命名框架相同的跨度分类和字段提取来识别您的跨度并提取评估人员需要的值。

由于您的框架自己的数据结构事先未知，因此该服务将每个值提取为字符串，而不是将其解析为特定于框架的结构。将提示、响应和工具参数保留在 “如何提取评估字段” 中列出的属性中，而不是封装在您自己的结构中，例如嵌套请求对象或自定义消息信封，以便评估者获得干净的值。

主题

支持的惯例

该服务选择如何从跨度中读取每个跨度scope.name。将仪器的作用域名称设置为以下前缀之一，服务将使用匹配的约定读取跨度：

会议 范围名称前缀

OpenTelemetry

opentelemetry.instrumentation.*

OpenInference

openinference.instrumentation.*

如果范围在本节中有自己的页面，则该服务将改用该页面上描述的处理方法。通用框架支持适用于与其中一个前缀匹配的所有其他范围。

有些范围与 OpenTelemetry 前缀相匹配，但不是 GenAI 代理框架。它们是传输和基础设施工具，例如 HTTP 客户端 (httpx、urllib3、urllib、aiohttp_client)、Web 框架 (starlette,fastapi)、模型上下文协议 (MCP) 工具和 Amazon SDK (botocore) 工具，包括其bedrock-agentcore和bedrock-runtime范围。该服务将这些范围排除在通用框架支持范围之外，这样它们的范围就不会产生虚假的代理、工具或推理跨度。

如何识别跨度

该服务使用其惯例的标准识别属性将每个跨度分为三种类型之一。在要评估的每个跨度上设置此属性。它的值告诉服务跨度代表什么，无论对话内容存储在哪里，服务都会从跨度本身读取跨度。

例
OpenTelemetry

该服务使用对跨度进行分类gen_ai.operation.name，并回退到操作名称不存在traceloop.span.kind时。

跨度类型 识别属性

调用代理

gen_ai.operation.name=invoke_agent（或 traceloop.span.kind =workflow）

执行工具

gen_ai.operation.name=execute_tool（或 traceloop.span.kind =tool）

推理

gen_ai.operation.name=chat（或 llm.request.type =chat）
OpenInference

该服务使用对跨度进行分类。openinference.span.kind

跨度类型 识别属性

调用代理

openinference.span.kind= AGENT 或 CHAIN

执行工具

openinference.span.kind = TOOL

推理

openinference.span.kind = LLM

如何提取评估字段

对于每个分类跨度，该服务会读取其所需的值，例如用户提示、代理响应以及工具输入和输出。与命名框架一样，对话内容的位置取决于遥测交付模式。使用分离式遥测，内容存在于相关的事件记录中。通过统一的遥测，它作为属性保持在跨度上。有关更多信息，请参阅遥测设置和交付。

该服务会为每个字段尝试多个位置，并使用第一个包含值的位置，因此您可以发出仪器已经设置的任何属性。每个提取的值都经过字符串化处理，而不是解析为特定于框架的结构。

OpenTelemetry 惯例

对于使用该 OpenTelemetry 约定的框架，该服务按顺序从以下位置读取每个字段：

  • 用户提示（调用代理跨度）：来自事件记录body.input；然后来自 gen_ai.task.input span 属性。

  • 代理响应（调用代理跨度）：来自事件记录body.output；然后来自gen_ai.task.output跨度属性。如果两者都不存在，则该服务会回退到从跟踪推理跨度收集的第一条用户消息和最后一条助手消息。

  • 推理消息（推理跨度）：来自事件记录body.output.messages；然后来自body.input.messagesgen_ai.input.messages和gen_ai.output.messages跨度属性。

  • 工具名称（执行工具跨度）：来自gen_ai.tool.name跨度属性；然后来自traceloop.entity.name跨度属性。

  • 工具参数（执行工具跨度）：来自gen_ai.tool.call.arguments跨度属性；然后来自事件记录body.input；然后来自traceloop.entity.input跨度属性。

  • 工具结果（执行工具跨度）：来自gen_ai.tool.call.result跨度属性；然后来自事件记录body.output；然后来自traceloop.entity.output跨度属性。

  • 系统提示（推理跨度）：来自 gen_ai.system_instructions span 属性。

OpenInference 惯例

对于使用该 OpenInference 约定的框架，该服务按顺序从以下位置读取每个字段：

  • 用户提示（调用代理跨度）：来自 input.value span 属性；然后来自事件记录正文输入。

  • 代理响应（调用代理跨度）：来自 output.value span 属性；然后来自事件记录正文输出。

  • 推理消息（推理跨度）：来自跨度的 OpenInference 消息属性（例如，llm.input_messages.*和llm.output_messages.*）；然后来自input.value和output.value；然后来自事件记录正文。

  • 工具参数（执行工具跨度）：来自 input.value span 属性；然后来自事件记录正文输入。

  • 工具结果（执行工具跨度）：来自 output.value span 属性；然后来自事件记录正文输出。

  • 系统提示（推理跨度）：来自推理范围属性；然后来自事件记录正文。

  • 可用工具：来自推理范围的工具定义属性 (llm.tools.*)；然后从事件记录正文中的序列化请求中解析出来，或. input.value

配置要求

要使用通用框架支持进行评估，请按以下方式配置您的仪器：

  • 使用可识别的范围名称。在以或开头的作用域名称下发射跨度。opentelemetry.instrumentation.* openinference.instrumentation.*该服务仅读取这些支持通用框架的前缀。

  • 在每个跨度上设置一个识别属性。traceloop.span.kind为gen_ai.operation.name约定设置或，或openinference.span.kind为 OpenInference 惯例设置或。 OpenTelemetry 该服务会跳过没有可识别的识别属性的跨度。

  • 将内容放入文档的属性中。设置如何提取评估字段中列出的提示、响应和工具属性。如果您将这些值包装在自己的结构中，则提取的值将包括周围的结构，因为该服务会对内容进行字符串化而不是解析框架的数据模型。

如果您无法设置惯例属性，则仍然可以评估顶级代理轮换。设置agentcore.invocation.user_prompt和agentcore.invocation.agent_response跨度属性， AgentCore SDK 也会发出这些属性。该服务从任何范围内读取这些属性，它们仅涵盖代理提示和响应，不涵盖推理或工具跨度。