Instrumentieren Sie Ihren Agenten Wie werden Spannweiten identifiziert Wie werden Bewertungsfelder extrahiert Beispiel für Zeitspannen mit Ereignisdatensätzen Beispiel: Spans ohne Ereignisdatensätze

OpenAI-Agenten

Auf dieser Seite wird erklärt, wie ein OpenAI Agents-Agent instrumentiert wird, wie Spans identifiziert werden und wie Bewertungsfelder extrahiert werden.

Topics

Instrumentieren Sie Ihren Agenten
Wie werden Spannweiten identifiziert
Wie werden Bewertungsfelder extrahiert
- Aus Ereignisaufzeichnungen
- Aus Span-Attributen
Beispiel für Spans mit Ereignisdatensätzen
Beispiel für Spans ohne Ereignisdatensätze

Instrumentieren Sie Ihren Agenten

Sie können einen OpenAI Agents-Agenten mit einer von zwei Instrumentierungsbibliotheken instrumentieren: OpenTelemetry(opentelemetry-instrumentation-openai-agents) oder OpenInference(openinference-instrumentation-openai-agents). Amazon Bedrock AgentCore Evaluations unterstützt beide Bibliotheken. Die Bibliotheken geben unterschiedliche Bereichsnamen aus und verwenden unterschiedliche Span-Attribute. Der Bewertungsservice extrahiert aus jedem die gleichen Werte.

Wenn Ihr Agent mit AWS Distro for OpenTelemetry (ADOT) ausgeführt wird, z. B. auf Amazon Bedrock AgentCore Runtime, müssen Sie keinen expliziten Instrumentierungscode hinzufügen. Es reicht aus, die Instrumentierungsbibliothek zu den Abhängigkeiten Ihres Projekts hinzuzufügen. ADOT erkennt es beim Start und aktiviert es automatisch.

Fügen Sie die Instrumentierungsbibliothek für den gewünschten Pfad zu Ihren Abhängigkeiten hinzu. Verwenden Sie die neueste verfügbare Version, es sei denn, Sie haben einen Grund zum Pin.

Beispiel

Anmerkung

Die Instrumentierung ist ein Schritt bei der Einrichtung der Beobachtbarkeit. Um Telemetrie zur Auswertung zu exportieren, schließen Sie die vollständigen Einstellungen unter Beobachtbarkeit einrichten ab.

Wie werden Spannweiten identifiziert

Das zur Klassifizierung von Spans verwendete Attribut unterscheidet sich zwischen den beiden Instrumentierungsbibliotheken.

Beispiel

OpenTelemetry

Die OpenTelemetry Instrumentierungsbibliothek klassifiziert Spans anhand des Attributs. gen_ai.operation.name

Typ der Spannweite	Identifizierendes Attribut
Agent aufrufen	`gen_ai.operation.name` = `invoke_agent`
Tool ausführen	`gen_ai.operation.name` = `execute_tool`
Inferenz	`gen_ai.operation.name` = `chat`

Anmerkung

OpenAI Agents gibt auch interne Turn-Boundary-Spans mit = aus. gen_ai.operation.name unknown Der Evaluierungsservice überspringt diese.

OpenInference

Die OpenInference Instrumentierungsbibliothek klassifiziert Spannweiten anhand des Attributs. openinference.span.kind

Typ der Spannweite	Identifizierendes Attribut
Agent aufrufen	`openinference.span.kind`= oder `AGENT` `CHAIN`
Tool ausführen	`openinference.span.kind` = `TOOL`
Inferenz	`openinference.span.kind` = `LLM`

Anmerkung

Bei der OpenInference Bibliothek handelt es sich bei den CHAIN Feldern AGENT und um leere Strukturcontainer: Sie enthalten keinen Konversationsinhalt. Die Benutzeraufforderung und die Antwort des Agenten werden anhand der Inference (LLM) -Spannen in derselben Ablaufverfolgung rekonstruiert.

Wie werden Bewertungsfelder extrahiert

OpenAI Agents serialisiert Nachrichten in einem teilbasierten Format, in dem jede Nachricht eine parts Reihe von typisierten Inhaltsblöcken enthält (z. B.). [{"role": "user", "parts": [{"type": "text", "content": "…"}]}] Mit der OpenTelemetry Bibliothek analysiert AgentCore Evaluations den Text aus diesen Teilen. Bei der OpenInference Bibliothek ist die Modellausgabe das vollständige OpenAI Response-Objekt, und AgentCore Evaluations liest den Antworttext ausoutput[].content[].text.

Der Speicherort dieser Inhalte hängt davon ab, wie die Telemetrie erfasst wurde. Das identifizierende Attribut (gen_ai.operation.nameoderopeninference.span.kind) befindet sich in beiden Fällen auf der Spanne. Weitere Informationen finden Sie unter Spans, Ereignisdatensätze und Telemetriesignale.

Aus Ereignisaufzeichnungen

Wenn die Telemetrie aufgeteilt wird, liest AgentCore Evaluations den Konversationsinhalt aus dem Ereignisdatensatz, der den einzelnen Zeiträumen zugeordnet ist. Die Position der Werkzeugeingaben und -ausgaben unterscheidet sich zwischen den beiden Bibliotheken:

OpenTelemetry:
- Benutzereingabe und Agentenantwort: aus dem Ereignisdatensatz des Invoke Agent Span, in body.input undbody.output.
- Werkzeugaufruf: der Werkzeugname von gen_ai.tool.name und die Argumente und das Ergebnis von gen_ai.tool.call.arguments und gen_ai.tool.call.result auf dem Ausführungs-Tool-Span. In der OpenTelemetry Bibliothek bleiben die Werkzeugargumente und Ergebnisse in den Span-Attributen erhalten, auch wenn die Telemetrie aufgeteilt wird.
OpenInference:
- Benutzereingabe und Antwort des Agenten: anhand des Ereignisdatensatzes der Inferenzspanne rekonstruiert. AgentCore Evaluations liest die Nachrichten von body.input und und body.output füllt dann den leeren Bereich für den Invoke Agent mit der Benutzeraufforderung und der Agentenantwort wieder auf.
- Werkzeugaufruf: der Name des Tools aus tool.name dem Bereich „Tool ausführen“. Die Werkzeugargumente und das Ergebnis stammen aus dem Ereignisdatensatz dieser Spanne, in body.input undbody.output.

Beispiele finden Sie unter Beispiel für Spans mit Ereignisdatensätzen.

Aus Span-Attributen

Wenn die Telemetrie nicht aufgeteilt wird, verbleibt derselbe Inhalt als Attribute im Bereich. Die Attribute hängen von der Instrumentierungsbibliothek ab:

OpenTelemetry:
- Benutzeraufforderung und Agentenantwort: von gen_ai.input.messages und nach gen_ai.output.messages dem Invoke Agent Span.
- Werkzeugaufruf: der Werkzeugname von gen_ai.tool.name und die Argumente und das Ergebnis von gen_ai.tool.call.arguments und gen_ai.tool.call.result im Bereich des Ausführungswerkzeugs.
OpenInference:
- Benutzereingabe und Antwort des Agenten: aus den indizierten Nachrichtenattributen im Inferenzbereich (llm.input_messages.undllm.output_messages.), dann wieder aufgefüllt in den leeren Bereich des Invoke Agents.
- Werkzeugaufruf: der Werkzeugname von tool.name und die Argumente und das Ergebnis von input.value und im Bereich des output.value Ausführungstools.

Beispiele finden Sie unter Beispielbereiche ohne Ereignisdatensätze.

Beispiel für Zeitspannen mit Ereignisdatensätzen

Wenn die Telemetrie aufgeteilt wird, enthält die Spanne die identifizierenden Attribute und der Inhalt befindet sich in einem korrelierten Ereignisdatensatz. Die folgenden Beispiele stammen von einem Reiseplanungsagenten von OpenAI Agents, der auf Amazon Bedrock Runtime eingesetzt wurde. AgentCore Derselbe Agent wird unter jeder Instrumentierungsbibliothek angezeigt.

Anmerkung

Bei diesen Beispielen handelt es sich nicht um vollständige Datenreihen. Sie zeigen repräsentative Daten aus einer echten Agenteninteraktion, wobei einige Felder weggelassen und lange Werte aus Gründen der Lesbarkeit gekürzt wurden.

OpenTelemetry

Beispiel

Invoke agent span

Das gen_ai.operation.name Attribut (invoke_agent) identifiziert dies als eine Spanne für den Aufruf-Agenten.


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

Der korrelierte Ereignisdatensatz enthält die Konversation. Jede Nachricht content ist das OpenAI-Array im Teileformat; die Benutzeraufforderung ist der Text der Benutzernachricht und die Antwort des Agenten ist der Text der Assistentennachricht.


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

Das gen_ai.operation.name Attribut (execute_tool) identifiziert dies als einen Bereich für das Ausführungstool; es gen_ai.tool.name enthält den Namen des Tools. Bei der OpenTelemetry Bibliothek bleiben die Werkzeugargumente und das Ergebnis in den Span-Attributen erhalten, auch wenn die Telemetrie aufgeteilt wird.


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

Das gen_ai.operation.name Attribut (chat) identifiziert dies als eine Inferenzspanne. Dieser Bereich enthält die Modellmetadaten und in diesem Zusammenhang die Liste der Toolsgen_ai.tool.definitions, die dem Agenten zur Verfügung stehen. Die Konversationsnachrichten für den Modellanruf befinden sich im korrelierten Ereignisdatensatz in body.input undbody.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

In der OpenInference Bibliothek ist der Invoke Agent (AGENT) -Bereich ein leerer Container. AgentCore Evaluations rekonstruiert die Benutzereingabe und die Antwort des Agenten anhand des Inference (LLM) -Bereichs, dessen Inhalt in einem korrelierten Ereignisdatensatz enthalten ist.

Beispiel

Invoke agent span

Das openinference.span.kind Attribut (AGENT) identifiziert dies als Span für den Aufruf des Agenten. Der Span enthält keinen Konversationsinhalt.


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

Das openinference.span.kind Attribut (TOOL) identifiziert dies als Span für das Ausführungstool; es tool.name enthält den Namen des Tools. Die Werkzeugargumente und das Ergebnis befinden sich im korrelierten Ereignisdatensatz.


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

Das openinference.span.kind Attribut (LLM) identifiziert dies als eine Inferenzspanne. Nachrichtenrollen und Tooldefinitionen befinden sich in den Span-Attributen; der Nachrichteninhalt befindet sich im korrelierten Ereignisdatensatz. ADOT reduziert die Eingaberollen aufuser, sodass AgentCore Evaluations die letzte Klartext-Eingabemeldung als Benutzeraufforderung verwendet. Die Ausgabenachricht ist das OpenAI Response-Objekt, aus dem AgentCore Evaluations den Antworttext liest.


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

Beispiel: Spans ohne Ereignisdatensätze

Wenn die Telemetrie nicht aufgeteilt wird, verbleibt derselbe Inhalt in den Span-Attributen und es wird kein separater Ereignisdatensatz erstellt. Die folgenden Beispiele stammen von einem Reiseplanungsagenten von OpenAI Agents. Derselbe Agent wird unter jeder Instrumentenbibliothek angezeigt.

Anmerkung

OpenTelemetry

Beispiel

Invoke agent span

Das gen_ai.input.messages Attribut enthält die Benutzeraufforderung und das gen_ai.output.messages Attribut enthält die Antwort des Agenten. Beide sind OpenAI-Arrays im Teileformat.


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

Das gen_ai.tool.call.arguments Attribut enthält die Werkzeugargumente und das gen_ai.tool.call.result Attribut enthält das Werkzeugergebnis.


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

Das gen_ai.operation.name Attribut (chat) identifiziert dies als eine Inferenzspanne. Die Modellmetadaten und das gen_ai.tool.definitions Attribut (die Liste der Tools, die dem Agenten zur Verfügung stehen) bleiben in der Spanne unverändert.


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

Beispiel

Execute tool span

Das input.value Attribut enthält die Werkzeugargumente und das output.value Attribut enthält das Werkzeugergebnis.


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

Der Nachrichteninhalt befindet sich direkt in den indizierten Attributen. Die llm.input_messages. Attribute enthalten die Systemaufforderung und die Benutzeraufforderung, und die llm.output_messages. Attribute enthalten die Agentenantwort. AgentCore Evaluations rekonstruiert die Benutzereingabe und die Agentenantwort aus diesem Bereich und füllt den leeren Bereich „Agent aufrufen“ () wieder auf. 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"
  }
}

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

LangGraph

LlamaIndex