对你的代理进行仪器如何识别跨度如何提取评估字段包含事件记录的示例没有事件记录的示例跨度

OpenAI 代理

本页介绍如何检测 OpenAI Agents 代理、如何识别跨度以及如何提取评估字段。

主题

对你的代理进行仪器
如何识别跨度
如何提取评估字段
- 来自事件记录
- 来自跨度属性
包含事件记录的示例
没有事件记录的示例跨度

对你的代理进行仪器

您可以使用两个插桩库中的任何一个来检测 OpenAI Agents 代理：OpenTelemetry(opentelemetry-instrumentation-openai-agents) 或 OpenInference(openinference-instrumentation-openai-agents)。Amazon Bedrock AgentCore 评估支持这两个库。这些库发出不同的作用域名称并使用不同的跨度属性。评估服务从每个值中提取相同的值。

当您的代理与 AWS Distro for OpenTelemetry (ADOT) 一起 AgentCore 运行时，例如在 Amazon Bedrock Runtime 上，您无需添加显式的检测代码。将仪器库添加到项目的依赖项中就足够了。ADOT 会在启动时发现它并自动将其激活。

为你想要的依赖关系路径添加仪器库。除非有理由固定，否则请使用最新的可用版本。

例

注意

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

如何识别跨度

用于对跨度进行分类的属性在两个仪器库中有所不同。

例

OpenTelemetry

OpenTelemetry 仪器库使用属性对跨度进行分类。gen_ai.operation.name

跨度类型	识别属性
调用代理	`gen_ai.operation.name` = `invoke_agent`
执行工具	`gen_ai.operation.name` = `execute_tool`
推理	`gen_ai.operation.name` = `chat`

注意

OpenAI Agents 还会以 = 发出内部转弯边界跨度。gen_ai.operation.name unknown评估服务会跳过这些。

OpenInference

OpenInference 仪器库使用属性对跨度进行分类。openinference.span.kind

跨度类型	识别属性
调用代理	`openinference.span.kind`= `AGENT` 或 `CHAIN`
执行工具	`openinference.span.kind` = `TOOL`
推理	`openinference.span.kind` = `LLM`

注意

在 OpenInference 库中，AGENT和CHAIN跨度是空的结构容器：它们不携带任何对话内容。用户提示和代理响应是根据同一条跟踪中的 inference (LLM) 跨度重建的。

如何提取评估字段

OpenAI Agents 以基于部分的格式序列化消息，其中每条消息都携带一parts组键入的内容块（例如）。[{"role": "user", "parts": [{"type": "text", "content": "…"}]}]使用该 OpenTelemetry 库， AgentCore 评估可以从这些部分中解析出文本。使用该 OpenInference 库，模型输出是完整的 OpenAI Response 对象， AgentCore 评估从中读取响应文本。output[].content[].text

这些内容的位置取决于遥测数据的收集方式。在这两种情况下，标识属性（gen_ai.operation.name或openinference.span.kind）都在跨度上。有关更多信息，请参阅跨度、事件记录和遥测信号。

来自事件记录

拆分遥测时， AgentCore 评估会从与每个跨度相关的事件记录中读取对话内容。两个库中工具输入和输出的位置不同：

OpenTelemetry:
- 用户提示和代理响应：来自调用代理跨度的事件记录，位于body.input和中body.output。
- 工具调用：来自的工具名称gen_ai.tool.name，以及执行工具跨度中的参数gen_ai.tool.call.arguments和gen_ai.tool.call.result结果。使用该 OpenTelemetry 库，即使遥测被拆分，工具参数和结果仍保留在跨度属性上。
OpenInference:
- 用户提示和代理响应：根据推理跨度的事件记录重建。 AgentCore 评估从body.input和读取消息body.output，然后使用用户提示和代理响应回填空的调用代理跨度。
- 工具调用：执行工具跨度tool.name上的工具名称。工具参数和结果来自该跨度的事件记录，位于body.input和中body.output。

有关示例，请参阅包含事件记录的跨度示例。

来自跨度属性

如果未拆分遥测，则相同的内容将作为属性保留在跨度上。这些属性取决于仪器库：

OpenTelemetry:
- 用户提示和代理响应：从gen_ai.input.messages和gen_ai.output.messages在调用代理跨度上。
- 工具调用：执行工具跨度上的工具名称gen_ai.tool.call.result，gen_ai.tool.call.arguments以及来自和的参数和结果。gen_ai.tool.name
OpenInference:
- 用户提示和代理响应：来自推理跨度（llm.input_messages.和llm.output_messages.）上的索引消息属性，然后回填到空的调用代理跨度。
- 工具调用：执行工具跨度上的工具名称output.value，input.value以及来自和的参数和结果。tool.name

有关示例，请参阅没有事件记录的跨度示例。

包含事件记录的示例

拆分遥测时，跨度带有识别属性，内容存在于相关的事件记录中。以下示例来自部署在亚马逊 Bedrock Runtime 上的 OpenAI Agents 旅行计划代理。 AgentCore 每个仪器库下都显示相同的代理。

注意

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

OpenTelemetry

例

Invoke agent span

gen_ai.operation.name属性 (invoke_agent) 将其标识为调用代理跨度。


{
  "traceId": "6a01eef11066751d68f90def0da1f80a",
  "spanId": "3a300b0b3fe650e4",
  "name": "invoke_agent openaiOtelTravel",
  "kind": "INTERNAL",
  "scope": {
    "name": "opentelemetry.instrumentation.openai_agents",
    "version": "0.62.1"
  },
  "attributes": {
    "gen_ai.operation.name": "invoke_agent",
    "gen_ai.agent.name": "openaiOtelTravel",
    "gen_ai.system": "openai",
    "gen_ai.provider.name": "openai",
    "gen_ai.request.model": "gpt-4o-mini-2024-07-18",
    "session.id": "sea-nyc-trip-2-turns-openai-otel"
  },
  "status": {
    "code": "OK"
  }
}

关联的事件记录载有对话。每条消息都content是 OpenAI 部分格式数组；用户提示是用户消息的文本，代理响应是助手消息的文本。


{
  "spanId": "3a300b0b3fe650e4",
  "traceId": "6a01eef11066751d68f90def0da1f80a",
  "scope": {
    "name": "opentelemetry.instrumentation.openai_agents"
  },
  "body": {
    "input": {
      "messages": [
        {
          "role": "user",
          "content": "[{\"role\": \"user\", \"parts\": [{\"type\": \"text\", \"content\": \"Hey, how can you help me\"}]}]"
        }
      ]
    },
    "output": {
      "messages": [
        {
          "role": "assistant",
          "content": "[{\"role\": \"assistant\", \"parts\": [{\"type\": \"text\", \"content\": \"I can assist you with planning your trips ...\"}]}]"
        }
      ]
    }
  }
}

Execute tool span

gen_ai.operation.name属性 (execute_tool) 将其标识为执行工具跨度；gen_ai.tool.name保存工具名称。使用该 OpenTelemetry 库，即使遥测被拆分，工具参数和结果仍保留在跨度属性上。


{
  "traceId": "6a01eefa5c52f3d86a35038f35f5ba30",
  "spanId": "3cbc4ea5f73fef81",
  "name": "execute_tool search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "opentelemetry.instrumentation.openai_agents",
    "version": "0.62.1"
  },
  "attributes": {
    "gen_ai.operation.name": "execute_tool",
    "gen_ai.tool.name": "search_flights",
    "gen_ai.tool.type": "function",
    "gen_ai.tool.call.arguments": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "gen_ai.tool.call.result": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"flights\": [ ... ]}",
    "session.id": "sea-nyc-trip-2-turns-openai-otel"
  },
  "status": {
    "code": "OK"
  }
}

Inference span

gen_ai.operation.name属性 (chat) 将其标识为推理跨度。此跨度包含模型元数据以及代理可用的工具列表。gen_ai.tool.definitions模型调用的对话消息显示在相关事件记录中，位于body.input和中。body.output


{
  "traceId": "6a01eef11066751d68f90def0da1f80a",
  "spanId": "7c1f9a2b4d6e8a03",
  "name": "openai.response",
  "kind": "INTERNAL",
  "scope": {
    "name": "opentelemetry.instrumentation.openai_agents",
    "version": "0.62.1"
  },
  "attributes": {
    "gen_ai.operation.name": "chat",
    "gen_ai.provider.name": "openai",
    "gen_ai.request.model": "gpt-4o-mini-2024-07-18",
    "gen_ai.response.model": "gpt-4o-mini-2024-07-18",
    "gen_ai.usage.input_tokens": 269,
    "gen_ai.usage.output_tokens": 78,
    "gen_ai.tool.definitions": "[{\"type\": \"function\", \"function\": {\"name\": \"search_flights\", \"description\": \"Search for available flights between cities.\", \"parameters\": { ... }}}]",
    "session.id": "sea-nyc-trip-2-turns-openai-otel"
  },
  "status": {
    "code": "OK"
  }
}


{
  "spanId": "7c1f9a2b4d6e8a03",
  "traceId": "6a01eef11066751d68f90def0da1f80a",
  "scope": {
    "name": "opentelemetry.instrumentation.openai_agents"
  },
  "body": {
    "input": {
      "messages": [
        {
          "role": "user",
          "content": "[{\"role\": \"user\", \"parts\": [{\"type\": \"text\", \"content\": \"Hey, how can you help me\"}]}]"
        }
      ]
    },
    "output": {
      "messages": [
        {
          "role": "assistant",
          "content": "[{\"role\": \"assistant\", \"parts\": [{\"type\": \"text\", \"content\": \"I can assist you with planning your trips ...\"}]}]"
        }
      ]
    }
  }
}

OpenInference

对于该 OpenInference 库，调用代理 (AGENT) 跨度是一个空容器。 AgentCore 评估会重建 inference (LLM) 跨度的用户提示和代理响应，其内容存在于相关的事件记录中。

例

Invoke agent span

openinference.span.kind属性 (AGENT) 将其标识为调用代理跨度。该跨度不包含对话内容。


{
  "traceId": "6a387ee61078243c1cc455ed45c6c313",
  "spanId": "9a1c7dce81b692cd",
  "name": "openaiOInfTravel",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.openai_agents",
    "version": "1.5.0"
  },
  "attributes": {
    "openinference.span.kind": "AGENT",
    "graph.node.id": "openaiOInfTravel",
    "llm.system": "openai",
    "session.id": "sea-nyc-trip-2-turns-openai-oi"
  },
  "status": {
    "code": "OK"
  }
}

Execute tool span

openinference.span.kind属性 (TOOL) 将其标识为执行工具跨度；tool.name保存工具名称。工具参数和结果将实时显示在相关的事件记录中。


{
  "traceId": "6a387ef07b8f4f3732fab45d3c0b51ff",
  "spanId": "b4e78cb0a06a6fe2",
  "name": "search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.openai_agents",
    "version": "1.5.0"
  },
  "attributes": {
    "openinference.span.kind": "TOOL",
    "tool.name": "search_flights",
    "input.mime_type": "application/json",
    "output.mime_type": "application/json",
    "session.id": "sea-nyc-trip-2-turns-openai-oi"
  },
  "status": {
    "code": "OK"
  }
}


{
  "spanId": "b4e78cb0a06a6fe2",
  "traceId": "6a387ef07b8f4f3732fab45d3c0b51ff",
  "scope": {
    "name": "openinference.instrumentation.openai_agents"
  },
  "body": {
    "input": {
      "messages": [
        { "role": "user", "content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}" }
      ]
    },
    "output": {
      "messages": [
        { "role": "assistant", "content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"flights\": [ ... ]}" }
      ]
    }
  }
}

Inference span

openinference.span.kind属性 (LLM) 将其标识为推理跨度。消息角色和工具定义位于跨度属性上；消息内容存在于相关的事件记录中。ADOT 将输入角色扁平化为user，因此 AgentCore 评估使用最后一条纯文本输入消息作为用户提示。输出消息是 OpenAI Response 对象， AgentCore 评估从中读取响应文本。


{
  "traceId": "6a387ee61078243c1cc455ed45c6c313",
  "spanId": "1221a062c7f90a8e",
  "name": "response",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.openai_agents",
    "version": "1.5.0"
  },
  "attributes": {
    "openinference.span.kind": "LLM",
    "llm.model_name": "gpt-4o-mini-2024-07-18",
    "llm.input_messages.0.message.role": "system",
    "llm.input_messages.1.message.role": "user",
    "llm.output_messages.0.message.role": "assistant",
    "llm.tools.0.tool.json_schema": "{\"type\": \"function\", \"function\": {\"name\": \"search_flights\", ...}}",
    "session.id": "sea-nyc-trip-2-turns-openai-oi"
  },
  "status": {
    "code": "OK"
  }
}


{
  "spanId": "1221a062c7f90a8e",
  "traceId": "6a387ee61078243c1cc455ed45c6c313",
  "scope": {
    "name": "openinference.instrumentation.openai_agents"
  },
  "body": {
    "input": {
      "messages": [
        { "role": "user", "content": "[{\"content\": \"Hey, how can you help me\", \"role\": \"user\"}]" },
        { "role": "user", "content": "You are a travel planning assistant. Help users plan trips ..." },
        { "role": "user", "content": "Hey, how can you help me" }
      ]
    },
    "output": {
      "messages": [
        {
          "role": "assistant",
          "content": "{\"id\": \"resp_abc123...\", \"output\": [{\"type\": \"message\", \"content\": [{\"type\": \"output_text\", \"text\": \"I can assist you with planning your trips ...\"}]}]}"
        }
      ]
    }
  }
}

没有事件记录的示例跨度

如果不拆分遥测，则相同的内容将保留在跨度属性上，并且不会生成单独的事件记录。以下示例来自 OpenAI Agents 的差旅计划代理。每个仪器库下都显示相同的代理。

注意

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

OpenTelemetry

例

Invoke agent span

该gen_ai.input.messages属性保存用户提示，该gen_ai.output.messages属性保存代理响应。两者都是 OpenAI 零件格式的数组。


{
  "traceId": "6a4de7b85e61747e6b568a1f4768e89d",
  "spanId": "50656fd77904d125",
  "name": "invoke_agent openaiOtelTravel",
  "kind": "INTERNAL",
  "scope": {
    "name": "opentelemetry.instrumentation.openai_agents",
    "version": "0.62.1"
  },
  "attributes": {
    "gen_ai.operation.name": "invoke_agent",
    "gen_ai.agent.name": "openaiOtelTravel",
    "gen_ai.system": "openai",
    "gen_ai.input.messages": "[{\"role\": \"user\", \"parts\": [{\"type\": \"text\", \"content\": \"Hey, how can you help me\"}]}]",
    "gen_ai.output.messages": "[{\"role\": \"assistant\", \"parts\": [{\"type\": \"text\", \"content\": \"I can assist you with planning your trips ...\"}]}]",
    "session.id": "sea-nyc-trip-2-turns-unified"
  },
  "status": {
    "code": "OK"
  }
}

Execute tool span

该gen_ai.tool.call.arguments属性保存工具参数，该gen_ai.tool.call.result属性保存工具结果。


{
  "traceId": "6a4de7c376913db82e6f0f336a16731d",
  "spanId": "8840e8e23724ebd7",
  "name": "execute_tool search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "opentelemetry.instrumentation.openai_agents",
    "version": "0.62.1"
  },
  "attributes": {
    "gen_ai.operation.name": "execute_tool",
    "gen_ai.tool.name": "search_flights",
    "gen_ai.tool.call.arguments": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "gen_ai.tool.call.result": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"flights\": [ ... ]}",
    "session.id": "sea-nyc-trip-2-turns-unified"
  },
  "status": {
    "code": "OK"
  }
}

Inference span

gen_ai.operation.name属性 (chat) 将其标识为推理跨度。模型元数据和gen_ai.tool.definitions属性（代理可用的工具列表）在跨度上保持内联。


{
  "traceId": "6a4de7b85e61747e6b568a1f4768e89d",
  "spanId": "9b2c1e5f7a3d0846",
  "name": "openai.response",
  "kind": "INTERNAL",
  "scope": {
    "name": "opentelemetry.instrumentation.openai_agents",
    "version": "0.62.1"
  },
  "attributes": {
    "gen_ai.operation.name": "chat",
    "gen_ai.provider.name": "openai",
    "gen_ai.request.model": "gpt-4o-mini-2024-07-18",
    "gen_ai.response.model": "gpt-4o-mini-2024-07-18",
    "gen_ai.usage.input_tokens": 269,
    "gen_ai.usage.output_tokens": 78,
    "gen_ai.tool.definitions": "[{\"type\": \"function\", \"function\": {\"name\": \"search_flights\", \"description\": \"Search for available flights between cities.\", \"parameters\": { ... }}}]",
    "session.id": "sea-nyc-trip-2-turns-unified"
  },
  "status": {
    "code": "OK"
  }
}

OpenInference

例

Execute tool span

该input.value属性保存工具参数，该output.value属性保存工具结果。


{
  "traceId": "6a387ef07b8f4f3732fab45d3c0b51ff",
  "spanId": "d5a1c9e70b46f312",
  "name": "search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.openai_agents",
    "version": "1.5.1"
  },
  "attributes": {
    "openinference.span.kind": "TOOL",
    "tool.name": "search_flights",
    "input.value": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "output.value": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"flights\": [ ... ]}",
    "session.id": "sea-nyc-trip-2-turns-oi"
  },
  "status": {
    "code": "OK"
  }
}

Inference span

消息内容在已编入索引的属性上是内联的。这些llm.input_messages.属性包含系统提示和用户提示，llm.output_messages.属性保存代理响应。 AgentCore 评估会重建此跨度的用户提示和代理响应，并回填空的 invoke agent () AGENT 跨度。


{
  "traceId": "6a387ee61078243c1cc455ed45c6c313",
  "spanId": "c9f0a2b41d773e88",
  "name": "response",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.openai_agents",
    "version": "1.5.1"
  },
  "attributes": {
    "openinference.span.kind": "LLM",
    "llm.model_name": "gpt-4o-mini-2024-07-18",
    "llm.input_messages.0.message.role": "system",
    "llm.input_messages.0.message.content": "You are a travel planning assistant ...",
    "llm.input_messages.1.message.role": "user",
    "llm.input_messages.1.message.content": "Hey, how can you help me",
    "llm.output_messages.0.message.role": "assistant",
    "llm.output_messages.0.message.contents.0.message_content.text": "I can assist you with planning your trips ...",
    "session.id": "sea-nyc-trip-2-turns-oi"
  },
  "status": {
    "code": "OK"
  }
}

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

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

文档惯例

LangGraph

LlamaIndex