# Agenti OpenAI
Questa pagina spiega come strumentare un agente [OpenAI Agents](https://openai.github.io/openai-agents-python/), come vengono identificati gli intervalli e come vengono estratti i campi di valutazione.
**Argomenti**
+ [Strumenta il tuo agente](#openai-agents-instrument)
+ [Come vengono identificate le campate](#openai-agents-span-identification)
+ [Come vengono estratti i campi di valutazione](#openai-agents-extraction)
+ [Dai registri degli eventi](#openai-agents-extraction-event-records)
+ [Dagli attributi span](#openai-agents-extraction-attributes)
+ [L'esempio si estende ai record degli eventi](#openai-agents-examples-with)
+ [Esempio di intervalli senza record di eventi](#openai-agents-examples-without)
## Strumenta il tuo agente
Puoi strumentare un agente OpenAI Agents con una delle due librerie di strumentazione: **OpenTelemetry**(`opentelemetry-instrumentation-openai-agents`) o (). **OpenInference**`openinference-instrumentation-openai-agents` Amazon Bedrock AgentCore Evaluations supporta entrambe le librerie. Le librerie emettono nomi di ambito diversi e utilizzano attributi span diversi. Il servizio di valutazione estrae gli stessi valori da ciascuna di esse.
Quando il tuo agente utilizza AWS Distro for OpenTelemetry (ADOT), ad esempio su Amazon Bedrock AgentCore Runtime, non è necessario aggiungere codice di strumentazione esplicito. È sufficiente aggiungere la libreria di strumentazione alle dipendenze del progetto. ADOT la rileva all'avvio e la attiva automaticamente.
Aggiungi la libreria di strumentazione per il percorso che desideri alle tue dipendenze. Utilizzate l'ultima versione disponibile a meno che non abbiate un motivo per bloccarla.
**Example**
NOTA: utilizza la versione `0.61.0` o successiva. Questa è la prima versione testata con il servizio di valutazione.
`opentelemetry-instrumentation-openai-agents`Aggiungila alle tue dipendenze. Il nome dell'ambito emesso è. `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: utilizza la versione `1.5.0` o successiva. Questa è la prima versione testata con il servizio di valutazione.
`openinference-instrumentation-openai-agents`Aggiungila alle tue dipendenze. Il nome dell'ambito emesso è. `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 strumentazione è un passo nella configurazione dell'osservabilità. [Per esportare la telemetria per la valutazione, completa la configurazione completa in Imposta l'osservabilità.](supported-frameworks.md#supported-frameworks-setup)
## Come vengono identificati gli intervalli
L'attributo utilizzato per classificare gli intervalli differisce tra le due librerie di strumentazione.
**Example**
La libreria di OpenTelemetry strumentazione classifica gli intervalli utilizzando l'attributo. `gen_ai.operation.name`
| Tipo di intervallo | Attributo identificativo |
| --- | --- |
| Invoca l'agente | `gen_ai.operation.name` = `invoke_agent` |
| Strumento di esecuzione | `gen_ai.operation.name` = `execute_tool` |
| Inferenza | `gen_ai.operation.name` = `chat` |
OpenAI Agents emette anche intervalli di turn-boundary interni con =. `gen_ai.operation.name` `unknown` Il servizio di valutazione li ignora.
La libreria di OpenInference strumentazione classifica gli intervalli utilizzando l'attributo. `openinference.span.kind`
| Tipo di intervallo | Attributo identificativo |
| --- | --- |
| Invoca l'agente | `openinference.span.kind`= `AGENT` o `CHAIN` |
| Strumento di esecuzione | `openinference.span.kind` = `TOOL` |
| Inferenza | `openinference.span.kind` = `LLM` |
Con la OpenInference libreria, gli `AGENT` and `CHAIN` span sono contenitori strutturali vuoti: non contengono contenuti di conversazione. Il prompt dell'utente e la risposta dell'agente vengono ricostruiti dagli intervalli di inferenza (`LLM`) nella stessa traccia.
## Come vengono estratti i campi di valutazione
OpenAI Agents serializza i messaggi in un formato basato su parti, in cui ogni messaggio contiene una `parts` serie di blocchi di contenuto digitati (ad esempio,). `[{"role": "user", "parts": [{"type": "text", "content": "…"}]}]` Con la OpenTelemetry libreria, Evaluations analizza il AgentCore testo da queste parti. Con la OpenInference libreria, l'output del modello è l'oggetto OpenAI Response completo e AgentCore Evaluations legge il testo della risposta da. `output[].content[].text`
La posizione di questo contenuto dipende da come è stata raccolta la telemetria. L'attributo identificativo (`gen_ai.operation.name`o`openinference.span.kind`) è presente nell'intervallo in entrambi i casi. Per ulteriori informazioni, consulta [Intervalli, record di eventi e segnali di telemetria](supported-frameworks-telemetry.md).
### Dai registri degli eventi
Quando la telemetria viene suddivisa, AgentCore Evaluations legge il contenuto della conversazione dal record dell'evento correlato a ciascun intervallo. La posizione degli input e degli output degli strumenti è diversa tra le due librerie:
+ **OpenTelemetry**:
+ **Richiesta dell'utente** e **risposta dell'agente**: dal record degli eventi di Invoke Agent Span, in and. `body.input` `body.output`
+ **Chiamata allo strumento**: il nome dello strumento da`gen_ai.tool.name`, gli argomenti e il risultato da `gen_ai.tool.call.arguments` e `gen_ai.tool.call.result` sull'intervallo dello strumento di esecuzione. Con la OpenTelemetry libreria, gli argomenti e i risultati dello strumento rimangono negli attributi span anche quando la telemetria viene suddivisa.
+ **OpenInference**:
+ **Richiesta dell'utente** e **risposta dell'agente**: ricostruita dal record degli eventi dell'inference span. AgentCore Evaluations legge i messaggi da `body.input` e `body.output` quindi riempie lo spazio vuoto dell'agente invoke con il prompt dell'utente e la risposta dell'agente.
+ **Tool call**: il nome dello strumento incluso nell'intervallo di esecuzione dello strumento. `tool.name` Gli argomenti e i risultati dello strumento provengono dal record degli eventi di quell'intervallo, in `body.input` and. `body.output`
Per esempi, vedete [Example spans with event records](#openai-agents-examples-with).
### Dagli attributi span
Quando la telemetria non viene suddivisa, lo stesso contenuto rimane nell'intervallo degli attributi. Gli attributi dipendono dalla libreria di strumentazione:
+ **OpenTelemetry**:
+ **Richiesta dell'utente** e **risposta dell'agente**: da `gen_ai.input.messages` e `gen_ai.output.messages` verso l'intervallo dell'agente di invocazione.
+ **Richiamata dello strumento**: il nome dello strumento da`gen_ai.tool.name`, gli argomenti e i risultati di `gen_ai.tool.call.arguments` e`gen_ai.tool.call.result`, nell'intervallo di esecuzione dello strumento.
+ **OpenInference**:
+ **Richiesta dell'utente** e **risposta dell'agente**: dagli attributi del messaggio indicizzati nell'intervallo di inferenza (`llm.input_messages. `and`llm.output_messages.`), quindi inserita nell'intervallo vuoto dell'agente di invoke.
+ **Chiamata allo strumento**: il nome dello strumento da`tool.name`, gli argomenti e il risultato di e, nell'intervallo dello strumento di `input.value` esecuzione. `output.value`
Ad esempio, vedete [Example spans without event records](#openai-agents-examples-without).
## L'esempio si estende ai record degli eventi
Quando la telemetria viene suddivisa, l'intervallo contiene gli attributi identificativi e il contenuto risiede in un record di eventi correlato. I seguenti esempi sono tratti da un agente di pianificazione dei viaggi di OpenAI Agents distribuito su Amazon Bedrock Runtime. AgentCore Lo stesso agente è mostrato in ogni libreria di strumentazione.
**Nota**
Questi esempi non sono intervalli completi. Mostrano dati rappresentativi derivanti da un'interazione con un agente reale, con alcuni campi omessi e valori lunghi troncati per motivi di leggibilità.
### OpenTelemetry
**Example**
L'`gen_ai.operation.name`attributo (`invoke_agent`) lo identifica come un invoke agent span.
```
{
"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"
}
}
```
Il record dell'evento correlato contiene la conversazione. Ogni messaggio `content` è l'array OpenAI parts-format; il prompt utente è il testo del messaggio dell'utente e la risposta dell'agente è il testo del messaggio dell'assistente.
```
{
"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 ...\"}]}]"
}
]
}
}
}
```
L'`gen_ai.operation.name`attributo (`execute_tool`) lo identifica come un intervallo di strumenti di esecuzione; contiene il nome dello strumento. `gen_ai.tool.name` Con la OpenTelemetry libreria, gli argomenti e i risultati dello strumento rimangono negli attributi span anche quando la telemetria viene suddivisa.
```
{
"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"
}
}
```
L'`gen_ai.operation.name`attributo (`chat`) lo identifica come un intervallo di inferenza. Questo intervallo contiene i metadati del modello e, al suo interno`gen_ai.tool.definitions`, l'elenco degli strumenti disponibili per l'agente. I messaggi di conversazione per la chiamata modello sono disponibili nel record degli eventi correlato, in and. `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
Con la OpenInference libreria, invoke agent (`AGENT`) span è un contenitore vuoto. AgentCore Evaluations ricostruisce il prompt dell'utente e la risposta dell'agente a partire dall'intervallo inference (`LLM`), il cui contenuto risiede in un record di eventi correlato.
**Example**
L'`openinference.span.kind`attributo (`AGENT`) lo identifica come un invoke agent span. Lo span non contiene alcun contenuto di conversazione.
```
{
"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"
}
}
```
L'`openinference.span.kind`attributo (`TOOL`) lo identifica come uno strumento di esecuzione; `tool.name` contiene il nome dello strumento. Gli argomenti e i risultati dello strumento risiedono nel record degli eventi correlato.
```
{
"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\": [ ... ]}" }
]
}
}
}
```
L'`openinference.span.kind`attributo (`LLM`) lo identifica come un intervallo di inferenza. I ruoli dei messaggi e le definizioni degli strumenti si trovano negli attributi span; il contenuto del messaggio risiede nel record dell'evento correlato. ADOT semplifica i ruoli di input in`user`, quindi AgentCore Evaluations utilizza l'ultimo messaggio di input in testo semplice come prompt dell'utente. Il messaggio di output è l'oggetto OpenAI Response, da cui AgentCore Evaluations legge il testo della risposta.
```
{
"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 ...\"}]}]}"
}
]
}
}
}
```
## L'esempio si estende senza record di eventi
Quando la telemetria non viene suddivisa, lo stesso contenuto rimane negli attributi span e non viene prodotto alcun record di eventi separato. I seguenti esempi sono tratti da un agente di pianificazione dei viaggi di OpenAI Agents. Lo stesso agente è mostrato in ogni libreria di strumentazione.
**Nota**
Questi esempi non sono intervalli completi. Mostrano dati rappresentativi derivanti da un'interazione con un agente reale, con alcuni campi omessi e valori lunghi troncati per motivi di leggibilità.
### OpenTelemetry
**Example**
L'`gen_ai.input.messages`attributo contiene il prompt dell'utente e l'attributo contiene la risposta dell'`gen_ai.output.messages`agente. Entrambi sono array in formato parti 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"
}
}
```
L'`gen_ai.tool.call.arguments`attributo contiene gli argomenti dello strumento e l'`gen_ai.tool.call.result`attributo contiene il risultato dello strumento.
```
{
"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"
}
}
```
L'`gen_ai.operation.name`attributo (`chat`) lo identifica come un intervallo di inferenza. I metadati del modello e l'`gen_ai.tool.definitions`attributo (l'elenco degli strumenti disponibili per l'agente) rimangono in linea nell'intervallo.
```
{
"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**
L'`input.value`attributo contiene gli argomenti dello strumento e l'`output.value`attributo contiene il risultato dello strumento.
```
{
"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"
}
}
```
Il contenuto del messaggio è in linea negli attributi indicizzati. Gli `llm.input_messages. ` attributi contengono il prompt di sistema e il prompt dell'utente e `llm.output_messages.` gli attributi contengono la risposta dell'agente. AgentCore Evaluations ricostruisce il prompt dell'utente e la risposta dell'agente a partire da questo intervallo e riempie lo span vuoto di 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"
}
}
```