Strumenta il tuo agente Come vengono identificati gli intervalli Come vengono estratti i campi di valutazione L'esempio si estende ai record degli eventi L'esempio si estende senza record di eventi

Agenti OpenAI

Questa pagina spiega come strumentare un agente OpenAI Agents, come vengono identificati gli intervalli e come vengono estratti i campi di valutazione.

Argomenti

Strumenta il tuo agente
Come vengono identificate le campate
Come vengono estratti i campi di valutazione
- Dai registri degli eventi
- Dagli attributi span
L'esempio si estende ai record degli eventi
Esempio di intervalli senza record di eventi

Strumenta il tuo agente

Puoi strumentare un agente OpenAI Agents con una delle due librerie di strumentazione: OpenTelemetry(opentelemetry-instrumentation-openai-agents) o (). OpenInferenceopeninference-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.

Esempio

Nota

La strumentazione è un passo nella configurazione dell'osservabilità. Per esportare la telemetria per la valutazione, completa la configurazione completa in Imposta l'osservabilità.

Come vengono identificati gli intervalli

L'attributo utilizzato per classificare gli intervalli differisce tra le due librerie di strumentazione.

Esempio

OpenTelemetry

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`

Nota

OpenAI Agents emette anche intervalli di turn-boundary interni con =. gen_ai.operation.name unknown Il servizio di valutazione li ignora.

OpenInference

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`

Nota

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.nameoopeninference.span.kind) è presente nell'intervallo in entrambi i casi. Per ulteriori informazioni, consulta Intervalli, record di eventi e segnali di telemetria.

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 dagen_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.

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 dagen_ai.tool.name, gli argomenti e i risultati di gen_ai.tool.call.arguments egen_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.andllm.output_messages.), quindi inserita nell'intervallo vuoto dell'agente di invoke.
- Chiamata allo strumento: il nome dello strumento datool.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.

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

Esempio

Invoke agent span

L'gen_ai.operation.nameattributo (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 ...\"}]}]"
        }
      ]
    }
  }
}

Execute tool span

L'gen_ai.operation.nameattributo (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"
  }
}

Inference span

L'gen_ai.operation.nameattributo (chat) lo identifica come un intervallo di inferenza. Questo intervallo contiene i metadati del modello e, al suo internogen_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.

Esempio

Invoke agent span

L'openinference.span.kindattributo (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"
  }
}

Execute tool span

L'openinference.span.kindattributo (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\": [ ... ]}" }
      ]
    }
  }
}

Inference span

L'openinference.span.kindattributo (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 inuser, 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

Esempio

Invoke agent span

L'gen_ai.input.messagesattributo contiene il prompt dell'utente e l'attributo contiene la risposta dell'gen_ai.output.messagesagente. 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"
  }
}

Execute tool span

L'gen_ai.tool.call.argumentsattributo contiene gli argomenti dello strumento e l'gen_ai.tool.call.resultattributo 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"
  }
}

Inference span

L'gen_ai.operation.nameattributo (chat) lo identifica come un intervallo di inferenza. I metadati del modello e l'gen_ai.tool.definitionsattributo (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

Esempio

Execute tool span

L'input.valueattributo contiene gli argomenti dello strumento e l'output.valueattributo 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"
  }
}

Inference span

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

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

LangGraph

LlamaIndex