Verfolgung und Observability
Auf dieser Seite
- Verfolgung und Observability
- Eingebaute Verfolgung
- Benennen von Verfolgungen
- Aufteilen eines Workflows in Schritte
- Benutzerdefinierte Verfolgungsprozessoren
- Exportieren in externe Systeme
- Die letzten Verfolgungen nicht verlieren
- Deaktivieren der Verfolgung
- Wichtige Kennzahlen zur Überwachung
- Wichtige Erkenntnisse
Aktualisiert am 3. November 2026. Verarbeitungsprozesse für Verfolgungsdaten (Trace Processors) haben zuvor versucht,
trace.start_time,trace.end_timeundspan.namezu lesen, die im SDK nicht existieren: Eine Verfolgung (Trace) besitzt kein Zeitstempel, und ein Span (Span) enthältstarted_at,ended_atsowiespan_data. Der Export-Prozess hat die abstrakte Methodeon_trace_startnicht implementiert: Die Instanziierung führte zu einerTypeError. „Verschachtelte Verfolgungen” (Nested traces) erstellten eine neue Verfolgung innerhalb einer anderen, was das SDK als wahrscheinlichen Fehler markiert: Schritte verwenden nuncustom_span(). Hinzugefügt:flush_traces(), der Umgang mit sensiblen Daten und Zero Data Retention. Der Code wurde mitopenai-agents0.24.0 verifiziert. Quellen: Verfolgung (SDK-Dokumentation) · openai-agents-python.
Verfolgung und Observability
Ein Agent in der Produktion ist eine Black Box, wenn Sie seine Aktionen nicht verfolgen. Wenn ein Kunde über eine absurde Antwort beschwert, haben Sie weder die genaue Anfrage, noch die aufgerufenen Tools, noch die Werte, die diese zurückgegeben haben. Das Verfolgung (Tracing) des SDKs zeichnet jeden Schritt der Ausführung auf: Modellaufrufe, eingesetzte Tools, Übergaben (Handoffs) und Schutzmechanismen (Guardrails). Dies ist Ihr wichtigstes Werkzeug zum Debuggen, Optimieren und Prüfen Ihrer Agenten.
Eingebaute Verfolgung
Gute Nachricht: Sie müssen nichts aktivieren. Das SDK verfolgt jede Ausführung automatisch und sendet standardmäßig Verfolgungsdaten an das OpenAI-Dashboard unter platform.openai.com. Der folgende Agent, geschrieben ohne einzige Verfolgungsanweisung, erzeugt bereits eine nutzbare Verfolgung.
from agents import Agent, Runner, function_tool
@function_tool
def search_product(name: str) -> str:
"""Sucht nach einem Produkt im Katalog."""
return f"Produkt gefunden: {name}, Preis €29.99"
agent = Agent(
name="Shop Agent",
instructions="Sie helfen Kunden bei der Suche nach Produkten.",
tools=[search_product],
model="gpt-5.6-terra",
)
# Jede Ausführung erstellt automatisch eine Verfolgung
result = Runner.run_sync(agent, "Suche nach dem Pro-Laptop")
Besuchen Sie das Dashboard, um die vollständige Verfolgung zu sehen: Dauer, verbrauchte Tokens, aufgerufene Tools und die finale Antwort.
Benennen von Verfolgungen
Nach einigen hundert Ausführungen wird das Dashboard zu einer undifferenzierten Liste. Geben Sie Ihren Verfolgungen aussagekräftige Namen, damit Sie sie leicht finden können – ein geschäftlicher Reise-Name ist besser als eine technische ID.
from agents import trace
with trace("premium-customer-order"):
result = await Runner.run(
agent,
"Ich möchte 5 Laptops für mein Team bestellen",
)
Der Verfolgungsname erscheint im Dashboard und erleichtert das Filtern.
Aufteilen eines Workflows in Schritte
Für einen Workflow mit mehreren Aufrufen öffnen Sie eine Verfolgung um das Ganze herum und markieren Sie jeden Schritt mit custom_span(). Verschachteln Sie keinen trace() innerhalb eines anderen: Das SDK protokolliert dann die Warnung Verfolgung existiert bereits. Erstellung einer neuen Verfolgung, dies ist jedoch wahrscheinlich ein Fehler. Spans hingegen sind dafür ausgelegt, verschachtelt zu sein: Jeder sitzt unter dem aktuellen Span.
from agents import Runner, custom_span, trace
async def process_order(message: str, conversation_id: str):
with trace("order-workflow", group_id=conversation_id):
with custom_span("step-1-understanding"):
result_understanding = await Runner.run(triage_agent, message)
with custom_span("step-2-processing"):
result_processing = await Runner.run(
order_agent,
result_understanding.to_input_list(),
)
with custom_span("step-3-confirmation", data={"step": 3}):
result_final = await Runner.run(
confirmation_agent,
result_processing.to_input_list(),
)
return result_final.final_output
Im Dashboard zeigt die order-workflow-Verfolgung die drei Schritte, und unter jedem davon die automatischen Spans der Ausführung: Agent, Modellaufrufe, Tools. Die group_id verknüpft Verfolgungen derselben Konversation, beispielsweise unter Verwendung Ihrer Thread-ID.
Standardmäßig umhüllt das SDK jeden Runner.run() in einer Verfolgung namens Agent workflow, und innerhalb dieser Verfolgungen der Agent, jede Modellgenerierung, jede Funktionsaufruf, jeden Schutzmechanismus (Guardrail) und jeden Übergang (Handoff). Für eine kompaktere Hierarchie schlägt die Dokumentation vor, die automatischen Task- und Turn-Spans zu unterdrücken:
from agents import RunConfig
result = await Runner.run(
agent,
"Hallo",
run_config=RunConfig(tracing={"include_task_and_turn_spans": False}),
)
Benutzerdefinierte Verfolgungsprozessoren
Das OpenAI-Dashboard ist bequem, aber Ihr Betriebsteam überwacht wahrscheinlich alles andere an anderer Stelle. Um Verfolgungsdaten an Ihr eigenes System zu senden, schreiben Sie einen Prozessor: Er empfängt Start- und Endereignisse, sowohl für die vollständige Verfolgung als auch für jeden Span. Alle sechs Methoden von TracingProcessor sind abstrakt: Implementieren Sie alle, auch wenn sie leer sind, sonst wird die Instanziierung fehlschlagen.
Hier ist, was jedes Objekt tatsächlich bereitstellt: Eine Verfolgung (Trace) hat eine trace_id und einen name, und ihre export()-Methode gibt auch group_id und metadata zurück; sie hat kein Zeitstempel. Ein Span hat span_id, trace_id, parent_id, started_at und ended_at (ISO 8601-Zeichenfolgen) sowie span_data, dessen type-Attribut agent, generation, function, handoff, guardrail, custom usw. ist. Die Verfolgungsdauer wird daher im Prozessor gemessen.
import time
from datetime import datetime
from typing import Any
from agents import add_trace_processor
from agents.tracing import Span, Trace, TracingProcessor
class MyTraceProcessor(TracingProcessor):
def __init__(self) -> None:
self._starts: dict[str, float] = {}
def on_trace_start(self, trace: Trace) -> None:
self._starts[trace.trace_id] = time.monotonic()
print(f"[TRACE START] {trace.name} - {trace.trace_id}")
def on_trace_end(self, trace: Trace) -> None:
duration = time.monotonic() - self._starts.pop(trace.trace_id, time.monotonic())
print(f"[TRACE END] {trace.name} - duration: {duration:.2f} s")
def on_span_start(self, span: Span[Any]) -> None:
print(f" [SPAN START] {span.span_data.type}")
def on_span_end(self, span: Span[Any]) -> None:
if span.started_at and span.ended_at:
duration = datetime.fromisoformat(span.ended_at) - datetime.fromisoformat(span.started_at)
print(f" [SPAN END] {span.span_data.type} - {duration.total_seconds():.2f} s")
def shutdown(self) -> None:
pass
def force_flush(self) -> None:
pass
add_trace_processor(MyTraceProcessor())
add_trace_processor() fügt Ihren Prozessor zum ursprünglichen hinzu: Verfolgungsdaten gehen weiterhin an das OpenAI-Dashboard. set_trace_processors() ersetzt die Standardprozessoren: Nichts geht mehr an OpenAI, es sei denn, Sie setzen dessen Exporter selbst wieder in die Liste.
Exportieren in externe Systeme
Für ein Observability-Tool müssen Sie lediglich die Spans neu formatieren. Das folgende Beispiel schreibt pro abgeschlossenen Span eine JSON-Zeile, ein Format, das die meisten Log-Sammler problemlos verarbeiten können; span.export() liefert bereits ein vollständiges Wörterbuch.
import json
import logging
from typing import Any
from agents.tracing import Span, Trace, TracingProcessor
logger = logging.getLogger("agent-traces")
class JsonExportProcessor(TracingProcessor):
"""Schreibt jeden abgeschlossenen Span als JSON für einen Log-Sammler."""
def on_trace_start(self, trace: Trace) -> None:
pass
def on_trace_end(self, trace: Trace) -> None:
logger.info(json.dumps(trace.export(), default=str))
def on_span_start(self, span: Span[Any]) -> None:
pass
def on_span_end(self, span: Span[Any]) -> None:
logger.info(json.dumps(span.export(), default=str))
def shutdown(self) -> None:
pass
def force_flush(self) -> None:
pass
Achten Sie darauf, was Sie exportieren: Standardmäßig enthalten Generierungs-Spans Modell-Eingaben und -Ausgaben, und Funktions-Spans Tool-Argumente und Ergebnisse. Um diese auszuschließen, übergeben Sie RunConfig(trace_include_sensitive_data=False) oder setzen Sie die Umgebungsvariable OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=false. Für fertige Integrationen listet die SDK-Dokumentation viele Drittanbieter-Tools auf, die ihren eigenen Prozessor bereitstellen.
Die letzten Verfolgungen nicht verlieren
Der Standard-Exporter sendet Verfolgungsdaten im Hintergrund, alle paar Sekunden. In einem Worker, der Aufgaben verarbeitet und nicht stoppt, oder in einem kurzen Skript rufen Sie flush_traces() nach dem Schließen der Verfolgung auf, um den Versand zu erzwingen:
from agents import flush_traces
with trace("nightly-processing"):
await Runner.run(agent, "Zusammenfassung der heutigen Tickets")
flush_traces() # nach Ende der Verfolgung, niemals in der Mitte
Deaktivieren der Verfolgung
Es gibt einen Fall, in dem Verfolgung mehr behindert als hilft: eine Testumgebung, die hunderte Mock-Agenten ausführt und Ihr Dashboard verschmutzt. In Tests oder während der lokalen Entwicklung können Sie sie daher deaktivieren, entweder global oder für eine einzelne Ausführung.
from agents import RunConfig, set_tracing_disabled
# Vollständig deaktivieren (oder Umgebungsvariable OPENAI_AGENTS_DISABLE_TRACING=1)
set_tracing_disabled(True)
# Oder für eine einzelne Ausführung
result = await Runner.run(agent, "Testnachricht", run_config=RunConfig(tracing_disabled=True))
Ein letzter Punkt, dieser vertragsrechtlich: Nach der Dokumentation ist die Verfolgung an OpenAI nicht verfügbar für Organisationen, die eine Zero Data Retention-Richtlinie anwenden. In diesem Fall erhalten Sie nur mit Ihrem eigenen Prozessor, installiert mit set_trace_processors(), Verfolgungsdaten.
Wichtige Kennzahlen zur Überwachung
Nun, worauf sollten Sie achten? In der Produktion reichen sechs Indikatoren aus, um die Gesundheit eines Agenten zu qualifizieren. Gesamtlatenz – die Zeit zwischen Anfrage und finaler Antwort – ist das, was Ihre Nutzer spüren; sie wird am häufigsten durch die Anzahl der Turns erklärt, also die Anzahl der Durchläufe des Agenten-Loops. Verbrauchte Tokens, sowohl Eingabe- als auch Ausgabe-Token pro Ausführung, treiben Ihre Rechnung.
Die anderen drei betreffen die Qualität. Die Tool-Fehlerquote, der Prozentsatz der Tools, die einen Fehler zurückgeben, offenbart eine instabile Drittanbieter-API oder schlecht generierte Argumente. Die Guardrail-Auslöserquote, sichtbar in guardrail-Spans, misst die Häufigkeit von Blockaden: Ein plötzlicher Anstieg signalisiert entweder einen Angriff oder einen Guardrail, der zu streng geworden ist. Schließlich zeigt die Übergabe-Verteilung (Handoff distribution), welcher Agent am häufigsten antwortet – und damit, ob Ihre Triage Anfragen dorthin sendet, wo sie hingehören.
Wichtige Erkenntnisse
- Das SDK verfolgt jede Ausführung automatisch an das OpenAI-Dashboard (außer für Organisationen mit Zero Data Retention)
- Eine
trace()pro Workflow; markieren Sie Schritte mitcustom_span()und verwenden Siegroup_id, um Verfolgungen einer Konversation zu verknüpfen - Eine Verfolgung hat keinen Zeitstempel; ein Span hat
started_at,ended_atundspan_data.type - Ein
TracingProcessorimplementiert seine sechs Methoden;add_trace_processor()fügt hinzu,set_trace_processors()ersetzt trace_include_sensitive_data=Falseschließt Eingaben und Ausgaben aus;flush_traces()erzwingt den Versand- Deaktivieren Sie in Tests die Verfolgung mit
set_tracing_disabled(True)oderRunConfig(tracing_disabled=True)