Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Verfolgung und Observability

Lektion 14 von 25 Aktualisiert am 3. November 2026 Entwickler
Auf dieser Seite
  1. Verfolgung und Observability
  2. Eingebaute Verfolgung
  3. Benennen von Verfolgungen
  4. Aufteilen eines Workflows in Schritte
  5. Benutzerdefinierte Verfolgungsprozessoren
  6. Exportieren in externe Systeme
  7. Die letzten Verfolgungen nicht verlieren
  8. Deaktivieren der Verfolgung
  9. Wichtige Kennzahlen zur Überwachung
  10. Wichtige Erkenntnisse

Aktualisiert am 3. November 2026. Verarbeitungsprozesse für Verfolgungsdaten (Trace Processors) haben zuvor versucht, trace.start_time, trace.end_time und span.name zu lesen, die im SDK nicht existieren: Eine Verfolgung (Trace) besitzt kein Zeitstempel, und ein Span (Span) enthält started_at, ended_at sowie span_data. Der Export-Prozess hat die abstrakte Methode on_trace_start nicht implementiert: Die Instanziierung führte zu einer TypeError. „Verschachtelte Verfolgungen” (Nested traces) erstellten eine neue Verfolgung innerhalb einer anderen, was das SDK als wahrscheinlichen Fehler markiert: Schritte verwenden nun custom_span(). Hinzugefügt: flush_traces(), der Umgang mit sensiblen Daten und Zero Data Retention. Der Code wurde mit openai-agents 0.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 mit custom_span() und verwenden Sie group_id, um Verfolgungen einer Konversation zu verknüpfen
  • Eine Verfolgung hat keinen Zeitstempel; ein Span hat started_at, ended_at und span_data.type
  • Ein TracingProcessor implementiert seine sechs Methoden; add_trace_processor() fügt hinzu, set_trace_processors() ersetzt
  • trace_include_sensitive_data=False schließt Eingaben und Ausgaben aus; flush_traces() erzwingt den Versand
  • Deaktivieren Sie in Tests die Verfolgung mit set_tracing_disabled(True) oder RunConfig(tracing_disabled=True)