Instrumente a su agente Cómo se identifican los intervalos Cómo se extraen los campos de evaluación Un ejemplo de tramos con registros de eventos El ejemplo abarca espacios sin registros de eventos

Agentes de OpenAI

En esta página se explica cómo instrumentar un agente de OpenAI Agents, cómo se identifican los intervalos y cómo se extraen los campos de evaluación.

Temas

Instrumente a su agente
¿Cómo se identifican los tramos
Cómo se extraen los campos de evaluación
- De los registros de eventos
- A partir de los atributos de span
Ejemplos de tramos con registros de eventos
Ejemplos de tramos sin registros de eventos

Instrumente a su agente

Puede instrumentar un agente de OpenAI Agents con una de las dos bibliotecas de instrumentación: OpenTelemetry(opentelemetry-instrumentation-openai-agents) o OpenInference(). openinference-instrumentation-openai-agents Amazon Bedrock AgentCore Evaluations es compatible con ambas bibliotecas. Las bibliotecas emiten distintos nombres de ámbito y utilizan distintos atributos de ámbito. El servicio de evaluación extrae los mismos valores de cada uno.

Cuando su agente utiliza la AWS Distro for OpenTelemetry (ADOT), como en Amazon Bedrock AgentCore Runtime, no necesita añadir código de instrumentación explícito. Basta con añadir la biblioteca de instrumentación a las dependencias de su proyecto. ADOT la descubre al inicio y la activa automáticamente.

Añada la biblioteca de instrumentación de la ruta que desee a sus dependencias. Usa la última versión disponible, a menos que tengas un motivo para marcarla.

ejemplo

nota

La instrumentación es un paso para configurar la observabilidad. Para exportar la telemetría para su evaluación, complete la configuración completa en Configurar la observabilidad.

Cómo se identifican los intervalos

El atributo utilizado para clasificar los intervalos difiere entre las dos bibliotecas de instrumentación.

ejemplo

OpenTelemetry

La biblioteca de OpenTelemetry instrumentación clasifica los tramos mediante el atributo. gen_ai.operation.name

Tipo de tramo	Atributo identificativo
Invoca al agente	`gen_ai.operation.name` = `invoke_agent`
Ejecute la herramienta	`gen_ai.operation.name` = `execute_tool`
Inferencia	`gen_ai.operation.name` = `chat`

nota

OpenAI Agents también emite intervalos de límite de turno internos con =. gen_ai.operation.name unknown El servicio de evaluación los omite.

OpenInference

La biblioteca de OpenInference instrumentación clasifica los tramos mediante el atributo. openinference.span.kind

Tipo de tramo	Atributo identificativo
Invoca al agente	`openinference.span.kind`= `AGENT` o `CHAIN`
Ejecute la herramienta	`openinference.span.kind` = `TOOL`
Inferencia	`openinference.span.kind` = `LLM`

nota

Con la OpenInference biblioteca, los intervalos AGENT y CHAIN los intervalos son contenedores estructurales vacíos: no contienen contenido de conversación. El mensaje del usuario y la respuesta del agente se reconstruyen a partir de los intervalos de inferencia (LLM) de la misma traza.

Cómo se extraen los campos de evaluación

Los agentes de OpenAI serializan los mensajes en un formato basado en partes, en el que cada mensaje incluye una parts serie de bloques de contenido mecanografiados (por ejemplo,). [{"role": "user", "parts": [{"type": "text", "content": "…"}]}] Con la OpenTelemetry biblioteca, AgentCore Evaluations analiza el texto de estas partes. Con la OpenInference biblioteca, la salida del modelo es el objeto de respuesta de OpenAI completo y AgentCore Evaluations lee el texto de la respuesta. output[].content[].text

La ubicación de este contenido depende de cómo se recopiló la telemetría. El atributo de identificación (gen_ai.operation.nameoopeninference.span.kind) está en el intervalo en ambos casos. Para obtener más información, consulte Intervalos, registros de eventos y señales de telemetría.

De los registros de eventos

Cuando se divide la telemetría, AgentCore Evaluaciones lee el contenido de la conversación del registro del evento correlacionado con cada intervalo. La ubicación de las entradas y salidas de las herramientas difiere entre las dos bibliotecas:

OpenTelemetry:
- Mensaje del usuario y respuesta del agente: del registro de eventos del grupo de agentes invocados, en body.input ybody.output.
- Llamada a la herramienta: el nombre de la herramienta desde el intervalo de la herramienta de ejecucióngen_ai.tool.name, los argumentos y el resultado desde gen_ai.tool.call.arguments y gen_ai.tool.call.result hacia el intervalo de la herramienta de ejecución. Con la OpenTelemetry biblioteca, los argumentos y los resultados de la herramienta permanecen en los atributos del intervalo incluso cuando se divide la telemetría.
OpenInference:
- Mensaje del usuario y respuesta del agente: reconstruidos a partir del registro de eventos del intervalo de inferencia. AgentCore Evaluations lee los mensajes body.input y body.output rellena el espacio vacío de invocación del agente con el mensaje del usuario y la respuesta del agente.
- Llamada de herramienta: el nombre de la herramienta que aparece tool.name en el intervalo de herramientas de ejecución. Los argumentos y el resultado de la herramienta provienen del registro de eventos de ese intervalo, en body.input ybody.output.

Para ver ejemplos, consulte Ejemplos de intervalos con registros de eventos.

De los atributos de span

Cuando la telemetría no está dividida, el mismo contenido permanece en el tramo que los atributos. Los atributos dependen de la biblioteca de instrumentación:

OpenTelemetry:
- Mensaje del usuario y respuesta del agente: desde gen_ai.input.messages y gen_ai.output.messages en el intervalo de invocación del agente.
- Llamada a la herramienta: el nombre de la herramienta desdegen_ai.tool.name, y los argumentos y el resultado de gen_ai.tool.call.arguments ygen_ai.tool.call.result, en el intervalo de la herramienta de ejecución.
OpenInference:
- Mensaje del usuario y respuesta del agente: a partir de los atributos del mensaje indexados en el intervalo de inferencia (llm.input_messages.yllm.output_messages.) y, a continuación, rellenados en el intervalo vacío de invocación del agente.
- Llamada a la herramienta: el nombre de la herramientatool.name, los argumentos y el resultado de input.value youtput.value, en el intervalo de la herramienta de ejecución.

Para ver ejemplos, consulte Ejemplos de intervalos sin registros de eventos.

Un ejemplo de tramos con registros de eventos

Cuando se divide la telemetría, el intervalo contiene los atributos de identificación y el contenido reside en un registro de eventos correlacionado. Los siguientes ejemplos provienen de un agente de planificación de viajes de OpenAI Agents implementado en Amazon Bedrock Runtime. AgentCore En cada biblioteca de instrumentación se muestra el mismo agente.

nota

Estos ejemplos no son períodos completos. Muestran datos representativos de una interacción real entre agentes, omitiendo algunos campos y truncando los valores largos para facilitar la lectura.

OpenTelemetry

ejemplo

Invoke agent span

El gen_ai.operation.name atributo (invoke_agent) lo identifica como un intervalo de agentes de invocación.


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

El registro de eventos correlacionados contiene la conversación. El de cada mensaje content es la matriz con formato de partes de OpenAI; el mensaje del usuario es el texto del mensaje del usuario y la respuesta del agente es el texto del mensaje del asistente.


{
  "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

El gen_ai.operation.name atributo (execute_tool) lo identifica como un intervalo de herramientas de ejecución; gen_ai.tool.name contiene el nombre de la herramienta. Con la OpenTelemetry biblioteca, los argumentos y el resultado de la herramienta permanecen en los atributos del intervalo incluso cuando se divide la telemetría.


{
  "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

El gen_ai.operation.name atributo (chat) lo identifica como un intervalo de inferencia. Este intervalo contiene los metadatos del modelo y, en ellagen_ai.tool.definitions, la lista de herramientas disponibles para el agente. Los mensajes de conversación de la llamada modelo se muestran en vivo en el registro de eventos correlacionados, en body.input ybody.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

En la OpenInference biblioteca, el intervalo invoke agent (AGENT) es un contenedor vacío. AgentCore Las evaluaciones reconstruyen el mensaje del usuario y la respuesta del agente a partir del intervalo inference (LLM), cuyo contenido se encuentra en un registro de eventos correlacionado.

ejemplo

Invoke agent span

El openinference.span.kind atributo (AGENT) lo identifica como un intervalo de agentes de invocación. El intervalo no incluye ningún contenido de conversación.


{
  "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

El openinference.span.kind atributo (TOOL) lo identifica como un intervalo de herramientas de ejecución; tool.name contiene el nombre de la herramienta. Los argumentos y el resultado de la herramienta se encuentran en el registro del evento correlacionado.


{
  "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

El openinference.span.kind atributo (LLM) lo identifica como un intervalo de inferencia. Las funciones de los mensajes y las definiciones de las herramientas se encuentran en los atributos del intervalo; el contenido del mensaje reside en el registro de eventos correlacionados. ADOT aplana las funciones de entradauser, por lo que AgentCore Evaluations utiliza el último mensaje de entrada de texto sin formato como mensaje de usuario. El mensaje de salida es el objeto de respuesta de OpenAI, desde el que AgentCore Evaluations lee el texto de la respuesta.


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

El ejemplo abarca espacios sin registros de eventos

Cuando la telemetría no está dividida, el mismo contenido permanece en los atributos del tramo y no se genera ningún registro de eventos independiente. Los siguientes ejemplos son de un agente de planificación de viajes de OpenAI Agents. En cada biblioteca de instrumentación se muestra el mismo agente.

nota

Estos ejemplos no son períodos completos. Muestran datos representativos de una interacción real entre agentes, omitiendo algunos campos y truncando los valores largos para facilitar la lectura.

OpenTelemetry

ejemplo

Invoke agent span

El gen_ai.input.messages atributo contiene la solicitud del usuario y la respuesta del gen_ai.output.messages agente. Ambas son matrices con formato de piezas 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

El gen_ai.tool.call.arguments atributo contiene los argumentos de la herramienta y el gen_ai.tool.call.result atributo contiene el resultado de la herramienta.


{
  "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

El gen_ai.operation.name atributo (chat) lo identifica como un intervalo de inferencia. Los metadatos del modelo y el gen_ai.tool.definitions atributo (la lista de herramientas disponibles para el agente) permanecen alineados en el intervalo.


{
  "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

ejemplo

Execute tool span

El input.value atributo contiene los argumentos de la herramienta y el output.value atributo contiene el resultado de la herramienta.


{
  "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

El contenido del mensaje está en línea en los atributos indexados. Los llm.input_messages. atributos contienen el mensaje del sistema y el mensaje del usuario, y los llm.output_messages. atributos contienen la respuesta del agente. AgentCore Evaluations reconstruye el mensaje del usuario y la respuesta del agente a partir de este intervalo y rellena el intervalo de invocación del agente () vacío. 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"
  }
}

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

LangGraph

LlamaIndex