Eine Sitzung umfasst sowohl die Unterhaltung mit deinem Agenten als auch seine Arbeit. Eine Sitzung kann mehrere Durchläufe umfassen. Jeder Durchlauf entspricht einem Arbeitszyklus. Ein Trace zeigt die einzelnen Schritte eines Durchlaufs, darunter Modellantworten, Tool-Aufrufe und Aufgaben, die der Agent an andere Agenten delegiert hat.
Im Tracing-Dashboard siehst du, was dein Agent getan hat. Für jeden Schritt findest du dort die aufgezeichneten Eingaben und Ausgaben sowie die Dauer und den Status.
Wie du Sitzungsstatus, Live-Ereignisse, gespeicherte Ausgaben und Nutzungsdaten über die API abrufst, erfährst du im Leitfaden zur Observability.
Für neue Sitzungen ist Tracing standardmäßig aktiviert. Du kannst Traces im Dashboard ansehen oder über die API exportieren.
Einen Trace öffnen
- Öffne Protokolle → Agenten und wähle das Projekt aus, in dem du deinen Agenten ausgeführt hast.
- Suche über Protokolle durchsuchen nach deiner Sitzung. Mit Filter hinzufügen kannst du nach Modell, Status oder Datum filtern.
- Wähle die Sitzung aus, um ihre Zeitleiste und die Liste der Durchläufe zu öffnen.
- Klappe einen Durchlauf auf und wähle in der Zeitleiste oder der Ereignisliste einen Schritt aus, um die Details zu sehen.
Die Sitzungsübersicht zeigt den Status, das Modell, die Startzeit, den Zeitpunkt der letzten Aktivität, die Anzahl der Durchläufe und den erfassten Token-Verbrauch.
Einen Trace lesen
Öffne zuerst die Sitzung und sieh dir dann einen einzelnen Durchlauf an.
- Sitzung: Jeder Eintrag unter Protokolle → Agenten entspricht einer Sitzung. Öffne den Eintrag, um die Zeitleiste und die Liste der Durchläufe zu sehen. So kann jemand beispielsweise nach einer Bestellung fragen und in derselben Sitzung eine Rückfrage stellen.
- Durchlauf: Klappe einen Durchlauf auf, um zu sehen, welche Arbeit der Agent in diesem Zyklus erledigt hat. Ein Durchlauf kann mehrere Modellantworten und Tool-Aufrufe umfassen. Eine weitere Nachricht nach Abschluss des Durchlaufs startet einen neuen Durchlauf in derselben Sitzung.
- Schritte im Durchlauf: Der Trace ordnet Modellantworten und Tool-Aufrufe dem Hauptagenten oder dem Subagenten zu, von dem sie stammen. Jeder aufgezeichnete Schritt heißt Span.
Wähle einen Span aus, um Status, Dauer, Start- und Endzeit sowie die aufgezeichneten Daten zu sehen.
| Auswahl | Angezeigte Details |
|---|---|
| Agent | Details zum Agenten, seine Anweisungen und sein erfasster Token-Verbrauch |
| Generation (eine Modellantwort) | Aufgezeichnete Eingaben und Ausgaben für eine Modellantwort |
| Tool | Aufgerufenes Tool, übergebene Argumente und, sofern verfügbar, das Ergebnis |
Agent
Ein Agenten-Span fasst die Arbeit des Hauptagenten oder eines Subagenten zusammen. Ein Subagent ist ein weiterer Agent, der einen Teil der Aufgabe übernimmt. Modellantworten und Tool-Aufrufe erscheinen unter dem Agenten, von dem sie stammen.
Die Detailansicht enthält folgende Angaben:
- Agententyp: Hauptagent (
root) oder Subagent (subagent). - Agent: ID, Name, Modell und Anweisungen des Agenten, sofern aufgezeichnet.
- Nutzung: die für diesen Agenten erfassten Token-Zahlen. Sie beziehen sich ausschließlich auf den Agenten selbst. Seine Subagenten werden separat erfasst.
- Dauer und Ergebnisstatus: wie lange die aufgezeichnete Arbeit gedauert hat und ob sie abgeschlossen wurde, fehlgeschlagen ist oder noch unvollständig ist.
Generation
Ein Generierungs-Span fasst die aufgezeichneten Modelleingaben und -ausgaben zusammen. Ein Durchlauf kann mehrere Generierungen umfassen.
Bei der Inferenz liest das Modell seine Eingabe und erzeugt eine Antwort. Diese Antwort kann einen Tool-Aufruf anfordern. Sobald das Tool sein Ergebnis zurückgibt, kann das Modell in einer neuen Generierung eine weitere Antwort erzeugen.
- Eingabe: die für diese Antwort aufgezeichneten Eingaben, etwa eine Nachricht der Person, die den Agenten nutzt, oder das Ergebnis eines Tools.
- Ausgabe: die aufgezeichneten Elemente, die das Modell erzeugt hat, etwa ein Antworttext oder ein Tool-Aufruf.
- Modell: das für die Antwort verwendete Modell, sofern aufgezeichnet.
Tool
Ein Tool-Span beschreibt einen Tool-Aufruf und dessen aufgezeichnetes Ergebnis.
Tool-Spans umfassen Aufrufe deiner Funktionen und von Tools auf Servern für MCP (Model Context Protocol). Auch Websuchen und die Ausführung von Befehlen können als Tool-Spans erscheinen.
- Aufruf: die Anfrage an das Tool mit Tool-Namen und Argumenten, sofern vorhanden.
- Ergebnis: die aufgezeichnete Antwort des Tools, sofern verfügbar.
- Ergebnisstatus und Fehler: das aufgezeichnete Ergebnis und gegebenenfalls Details zum Fehler.
Bei einem MCP-Tool-Aufruf enthält Aufruf die Serverbezeichnung (server_label), den Tool-Namen (name) und die Argumente (arguments). Antwort und Fehler werden dort, sofern verfügbar, als output und error aufgezeichnet. Der separate Bereich Ergebnis kann leer sein, weil die MCP-Antwort unter Aufruf gespeichert ist.
Zeitlicher Ablauf und Status
Die Zeitleiste zeigt, in welcher Reihenfolge die Schritte ablaufen und welche sich überschneiden. Mit Vergrößern kannst du kürzere Schritte genauer betrachten. Mit Zeitleiste einpassen siehst du die gesamte Sitzung.
Jeder Span zeigt seine Dauer und seinen Ergebnisstatus. Bei fehlgeschlagenen Spans können auch aufgezeichnete Fehlerdetails erscheinen.
Die Dauer eines Agenten-Spans schließt seine untergeordneten Schritte ein. Schritte können sich überschneiden. Laufen zwei Subagenten gleichzeitig jeweils 10 Sekunden lang, vergehen insgesamt etwa 10 Sekunden.
Token-Verbrauch
Unter Token siehst du in der Sitzungsübersicht den Verbrauch der gesamten Sitzung. Unter Nutzung findest du im Agenten-Span die für diesen Agenten erfassten Token-Zahlen.
Nutzungsdaten können auch nach Ende des Durchlaufs eintreffen. Ein leeres Feld oder null bedeutet, dass die Anzahl unbekannt ist. Der Agent kann also durchaus Token verbraucht haben. Die Zahlen können sich ändern, sobald weitere Nutzungsdaten vorliegen. Sie stellen keine endgültige Abrechnung dar.
Wann Traces verfügbar sind
Traces entstehen nach Abschluss eines Durchlaufs. Die Antwort des Agenten kann bereits erscheinen, bevor der Trace oder die Angaben zum Token-Verbrauch verfügbar sind.
Anhand der Live-Ereignisse einer Sitzung kannst du den Fortschritt verfolgen, während der Agent noch arbeitet.
Sitzungs-Traces exportieren
Lade Sitzungs-Traces herunter, um sie in einem anderen Tracing-Tool zu untersuchen. Der Endpunkt GET /v1/agents/sessions/{session_id}/traces liefert eine Seite mit Traces im JSON-Format des OpenTelemetry Protocol (OTLP).
Der Trace-Export muss für deine Organisation aktiviert sein. Verwende einen API-Schlüssel für das Projekt der Sitzung. Er benötigt entweder die Leseberechtigung für Traces (api.traces.read) oder die weiter gefasste Leseberechtigung für Agenten (api.agents.read).
Setze OPENAI_API_KEY und ersetze sess_123 durch deine Sitzungs-ID. Dieses Beispiel verwendet cURL und jq, um eine Seite als traces.otlp.json zu speichern:
curl --fail-with-body \
"https://api.openai.com/v1/agents/sessions/sess_123/traces?limit=20&order=asc" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: agents=v1" \
--output trace-page.json && \
jq '{resourceSpans: [.data[].otlp.resourceSpans[]]}' trace-page.json > traces.otlp.jsonDer Befehl fasst die Traces dieser Seite zu einer OTLP-Payload zusammen. Sende sie an den OTLP/HTTP-Endpunkt deines Tracing-Anbieters und verwende dessen Authentifizierungsverfahren.
Prüfe trace-page.json, um die gesamte Sitzung zu exportieren. Wenn has_more den Wert true hat, fordere die nächste Seite an. Übergib dazu last_id als after und behalte denselben Wert für order bei. Speichere jede Seite oder lade sie hoch, bevor du die nächste abrufst. Wiederhole den Vorgang, bis has_more den Wert false hat.
Jeder Export enthält nur die Traces, die zum Zeitpunkt der jeweiligen Anfrage verfügbar sind. Wenn du eine vergangene Sitzung exportieren möchtest, warte, bis alle Durchläufe beendet sind, und plane anschließend Zeit ein, bis die Traces verfügbar sind. Der Export richtet keine automatische Übermittlung künftiger Traces ein.
Traces für einen Agenten exportieren
Um Traces aus mehreren Sitzungen eines Agenten zu exportieren, rufe zunächst die Sitzungsliste ab und verwende dabei den Filter agent_id. Ersetze agent_123 durch die ID deines Agenten:
curl --fail-with-body \
"https://api.openai.com/v1/agents/sessions?agent_id=agent_123&limit=100&order=asc" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "OpenAI-Beta: agents=v1"- Verwende für jede Sitzung in
dataderenid, um wie oben beschrieben alle Seiten mit Sitzungs-Traces zu exportieren. - Enthält die Sitzungsliste
has_more: true, übergib den Wert vonlast_idaus dieser Liste alsafter, um die nächste Seite abzurufen. Behalte dieselben Werte füragent_idundorderbei. - Wiederhole den Vorgang, bis die Sitzungsliste
has_more: falseenthält.
Der Filter bezieht sich auf den Hauptagenten der Sitzung. Halte den Cursor für die Sitzungsliste vom Trace-Cursor der jeweiligen Sitzung getrennt.
Beispiel: Ein Durchlauf mit zwei Subagenten
Dieses Beispiel stammt aus einer aufgezeichneten Sitzung. Der Hauptagent ruft ein MCP-Tool auf, während ein Subagent einen Befehl ausführt und ein zweiter Dokumente abruft. Die Namen der Subagenten sind hier vereinfacht. Die Zahlen und Zeitangaben stammen aus dem aufgezeichneten Trace.
Sitzung und Durchlauf
Im Kopfbereich der Sitzung stehen 1 Durchlauf, 10 Tool-Aufrufe und 252.468 Token. Die Sitzung hat den Status Inaktiv. Durchlauf 1 hat den Status Abgeschlossen und dauerte 1 min 37 s.
Wenn du den Durchlauf aufklappst, siehst du den Hauptagenten und seine untergeordneten Schritte. Der Trace enthält 3 Agenten-Spans (den Hauptagenten und zwei Subagenten), 11 Generierungs-Spans und 10 Tool-Spans.
Die Baumansicht fasst wiederholte Generierungen und Tool-Aufrufe zusammen. Sie zeigt, welchem übergeordneten Schritt sie jeweils zugeordnet sind. In der Zeitleiste siehst du, wann jeder Schritt ausgeführt wurde.
Session: Idle
└── Turn 1: Completed 1m 37s
└── Root agent 1m 37s
├── 6 generations
├── 2 tools: spawn_agent_call
├── Subagent A 24s
│ ├── 2 generations
│ └── Tool: command_execution 2s
├── Subagent B 21s
│ ├── 3 generations
│ ├── 2 tools: notion.fetch 2s each
│ └── Tool: send_input_call 0ms
├── Tool: demo_capability_probe 87ms
└── 3 tools: wait_for_agents_call
Modellantworten und delegierte Aufgaben
Die erste Generation des Hauptagenten enthält unter Eingabe die Nachricht der Person, die die Anfrage gestellt hat. Die Ausgabe enthält Nachrichten und zwei Elemente vom Typ spawn_agent_call. Diese Aufrufe erscheinen auch als Spans vom Typ Tool. Die dadurch gestarteten Subagenten erscheinen unter dem Hauptagenten als Spans vom Typ Agent.
Subagent A hat eigene Generierungen und einen Tool-Aufruf vom Typ command_execution. Subagent B hat drei Generierungen, zwei MCP-Aufrufe von notion.fetch und einen Aufruf vom Typ send_input_call. Die Modellantworten und Tool-Aufrufe sind dem Span des jeweiligen Subagenten zugeordnet.
Zum Hauptagenten gehören außerdem drei Tool-Spans vom Typ wait_for_agents_call. Seine letzte Generierung enthält eine Nachricht. Die aufgezeichnete Dauer beträgt 6 s.
Ein MCP-Tool-Aufruf
Der Span demo_capability_probe des Hauptagenten ist ein abgeschlossener Span vom Typ Tool mit einer Dauer von 87 ms. Als Tool-Typ ist mcp_call angegeben.
Der Bereich Aufruf enthält unter anderem diese Felder:
{
"type": "mcp_call",
"server_label": "demo_local",
"name": "demo_capability_probe",
"status": "completed"
}
Dieser Ausschnitt zeigt einen Teil des aufgezeichneten Aufrufs. Im selben Bereich stehen die Argumente in arguments und die MCP-Antwort in output. Der separate Bereich Ergebnis hat den Wert null. Der übergeordnete Span verweist auf den Hauptagenten.
Die beiden notion.fetch-Spans von Subagent B sind genauso aufgebaut. Der Tool-Typ ist mcp_call, die MCP-Antwort steht unter Aufruf, und beide Spans sind dem Subagenten untergeordnet.
Zeitlicher Ablauf und Token-Verbrauch in dieser Sitzung
Die beiden Subagenten-Spans überschneiden sich auf der Zeitleiste. Subagent A benötigt 24 s, Subagent B 21 s. Beide arbeiten innerhalb des 1 min 37 s langen Spans des Hauptagenten. Das Dashboard zeigt die gerundeten Zeitangaben an.
Im Bereich Nutzung jedes Agenten-Spans siehst du die Token-Zahlen, die für diesen Agenten erfasst wurden:
| Agent | Eingabe-Token | Ausgabe-Token | Token insgesamt |
|---|---|---|---|
| Hauptagent | 126.390 | 1.567 | 127.957 |
| Subagent A | 34.075 | 465 | 34.540 |
| Subagent B | 89.304 | 667 | 89.971 |
In dieser aufgezeichneten Sitzung ergeben die Gesamtwerte der drei Agenten zusammen die 252.468 Token, die im Kopfbereich der Sitzung angezeigt werden.