# Agentes de OpenAI
En esta página se explica cómo instrumentar un agente de [OpenAI Agents](https://openai.github.io/openai-agents-python/), cómo se identifican los intervalos y cómo se extraen los campos de evaluación.
**Temas**
+ [Instrumente a su agente](#openai-agents-instrument)
+ [¿Cómo se identifican los tramos](#openai-agents-span-identification)
+ [Cómo se extraen los campos de evaluación](#openai-agents-extraction)
+ [De los registros de eventos](#openai-agents-extraction-event-records)
+ [A partir de los atributos de span](#openai-agents-extraction-attributes)
+ [Ejemplos de tramos con registros de eventos](#openai-agents-examples-with)
+ [Ejemplos de tramos sin registros de eventos](#openai-agents-examples-without)
## 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.
**Example**
NOTA: Usa la versión `0.61.0` o posterior. Esta es la primera versión probada con el servicio de evaluación.
Añada `opentelemetry-instrumentation-openai-agents` a sus dependencias. El nombre del ámbito emitido es`opentelemetry.instrumentation.openai_agents`.
`requirements.txt`:
```
opentelemetry-instrumentation-openai-agents>=0.61.0
```
`pyproject.toml`:
```
[project]
dependencies = [
"opentelemetry-instrumentation-openai-agents>=0.61.0",
]
```
NOTA: Utilice la versión `1.5.0` o posterior. Esta es la primera versión probada con el servicio de evaluación.
Añada `openinference-instrumentation-openai-agents` a sus dependencias. El nombre del ámbito emitido es`openinference.instrumentation.openai_agents`.
`requirements.txt`:
```
openinference-instrumentation-openai-agents>=1.5.0
```
`pyproject.toml`:
```
[project]
dependencies = [
"openinference-instrumentation-openai-agents>=1.5.0",
]
```
**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.](supported-frameworks.md#supported-frameworks-setup)
## Cómo se identifican los intervalos
El atributo utilizado para clasificar los intervalos difiere entre las dos bibliotecas de instrumentación.
**Example**
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` |
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.
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` |
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.name`o`openinference.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](supported-frameworks-telemetry.md).
### 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` y`body.output`.
+ **Llamada a la herramienta**: el nombre de la herramienta desde el intervalo de la herramienta de ejecución`gen_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` y`body.output`.
Para ver ejemplos, consulte [Ejemplos de intervalos con registros de eventos](#openai-agents-examples-with).
### 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 desde`gen_ai.tool.name`, y los argumentos y el resultado de `gen_ai.tool.call.arguments` y`gen_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. `y`llm.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 herramienta`tool.name`, los argumentos y el resultado de `input.value` y`output.value`, en el intervalo de la herramienta de ejecución.
Para ver ejemplos, consulte [Ejemplos de intervalos sin registros de eventos](#openai-agents-examples-without).
## 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
**Example**
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 ...\"}]}]"
}
]
}
}
}
```
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"
}
}
```
El `gen_ai.operation.name` atributo (`chat`) lo identifica como un intervalo de inferencia. Este intervalo contiene los metadatos del modelo y, en ella`gen_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` y`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
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.
**Example**
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"
}
}
```
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\": [ ... ]}" }
]
}
}
}
```
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 entrada`user`, 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
**Example**
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"
}
}
```
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"
}
}
```
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
**Example**
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"
}
}
```
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"
}
}
```