Replay und Debugging für KI-Agenten

Idee in 30 Sekunden

Replay für KI-Agenten bedeutet: einen realen problematischen Trace nehmen, ihn unter kontrollierten Bedingungen reproduzieren und die Fehlerursache Schritt für Schritt finden.

Der Hauptwert ist, dass das Team die Incident-Ursache nicht rät. Es sieht die gesamte Kette von Agentenentscheidungen und den exakten Punkt, an dem das Verhalten gebrochen ist.

Problem

Ohne replay debuggen Teams oft "aus dem Gedächtnis":

• sie sehen nur die finale Agentenantwort;
• der vollständige Kontext der Anfrage fehlt;
• Ergebnisse von Tool-Aufrufen pro Schritt sind nicht sichtbar.

In diesem Modus ist es schwer, Symptom und Ursache zu trennen. Fixes werden ungenau, und Incidents kommen wieder.

Typische Folgen:

• Fehler wird lokal behoben, aber reales Production-Szenario nicht reproduziert;
• nach dem Release erscheint dieselbe Fehlerklasse erneut;
• das Team verliert Zeit mit wiederholten manuellen Analysen.

Wann einsetzen

Replay wird genutzt, wenn:

• in Production ein Incident aufgetreten ist und root cause gefunden werden muss;
• nach Modell- oder Prompt-Änderung ein unerwarteter diff im Verhalten erscheint;
• ein Regression-Test einen kritischen Case als fehlgeschlagen zeigt;
• geprüft werden muss, dass ein Fix das Incident-Szenario wirklich schließt.

Replay ist am nützlichsten in Systemen mit mehrstufigem Agentenverhalten und externen Tools.

Umsetzung

In der Praxis folgt replay einem Prinzip: gleicher Trace, gleiche Laufbedingungen, schrittweise Analyse der Entscheidungen. Die Beispiele unten sind schematisch und nicht an ein konkretes Framework gebunden.

Wie es in einer Analyse funktioniert

1. Trace mit vollständigem Kontext speichern

trace = {
    "trace_id": "incident-2026-03-11-42",
    "input": "Refund order #8472",
    "conversation_state": {"user_tier": "pro"},
    "steps": [
        {"tool": "payments_api", "args": {"order_id": "8472"}, "result": {"status": "timeout"}},
        {"tool": "fallback_policy", "args": {}, "result": {"action": "ask_for_retry"}}
    ],
    "final_output": "Please try again later.",
    "stop_reason": "fallback_used",
}

Ohne vollständigen Trace reproduziert replay die reale Incident-Ursache fast nie.

2. Trace unter denselben Bedingungen reproduzieren

def replay_trace(agent, trace, runtime_config):
    return agent.replay(
        trace=trace,
        model_version=runtime_config["model_version"],
        tool_mocks=runtime_config["tool_mocks"],
        timeout_sec=runtime_config["timeout_sec"],
    )

Wenn Modell, Timeouts oder Tool-Bedingungen abweichen, kann Replay fälschlich sicher wirken.

3. Schritt-Timeline analysieren

def find_first_bad_step(replayed_steps):
    return next(
        ((idx, step) for idx, step in enumerate(replayed_steps) if step["status"] == "unexpected"),
        None,
    )

Ziel des Debuggings ist, den ersten Schritt zu finden, an dem das System vom erwarteten Pfad abweicht.

4. Root cause strukturiert festhalten

incident_report = {
    "trace_id": "incident-2026-03-11-42",
    "root_cause": "tool_timeout_not_handled_as_retryable",
    "affected_component": "retry_policy",
    "fix_plan": "treat payments timeout as retryable before fallback",
}

Eine strukturierte root cause vereinfacht Fix-Verifikation und Wissenstransfer im Team.

5. Incident in das Regression-Set aufnehmen

def promote_to_regression_case(trace, report):
    return {
        "id": trace["trace_id"],
        "input": trace["input"],
        "expected_behavior": {"stop_reason": "resolved"},
        "tags": ["incident", "replay", report["affected_component"]],
    }

Nach der Replay-Analyse sollte der Case in regression oder golden dataset aufgenommen werden, sonst kann der Incident wieder auftreten.

QA- und Automatisierungsnotizen

QA-Teams nutzen Replay in der Regel, um Production-Fehler in einer kontrollierten Umgebung zu reproduzieren und die Incident-Ursache Schritt für Schritt zu untersuchen.

In der Praxis funktioniert das als automatisierter Zyklus: Der Incident-Trace wird in einen Replay-Run eingespeist, die Ergebnisse werden im Untersuchungsbericht festgehalten, und der bestätigte Case wird in das Regression-Set aufgenommen.

Typische Fehler

Unvollständiger Incident-Trace

In Logs steht die finale Antwort, aber es fehlen Agenten-Schritte und Tool-Ergebnisse.

Typische Ursache: es wird nur Summary ohne Schritt-Details gespeichert.

Replay in anderen Runtime-Bedingungen

Der Trace wird mit anderem Modell oder anderen timeout/retry-Werten reproduziert.

Typische Ursache: Runtime-Bedingungen des Incidents sind nicht fixiert.

Nur finalen Text debuggen

Das Team analysiert nur die letzte Antwort und übersieht die Ursache in der Mitte des Runs.

Typische Ursache: es gibt keine schrittweise Timeline von Agentenentscheidungen.

Root cause wird nicht strukturiert dokumentiert

Nach dem Incident gibt es eine mündliche Schlussfolgerung, aber keinen klaren technischen Eintrag.

Typische Ursache: es fehlt eine Vorlage für Incident-Reports.

Case wird nicht in Regression aufgenommen

Incident wurde gefixt, aber nicht in den dauerhaften Testsatz übernommen.

Typische Ursache: Replay-Analyse ist vom Regression-Workflow getrennt.

Kurzfassung

FAQ

Q: Worin unterscheidet sich replay von regression testing?
A: Regression vergleicht Systemversionen auf Case-Sets, replay reproduziert einen konkreten realen Incident zur root-cause-Suche.

Q: Was ist das Minimum für qualitatives Replay?
A: input, Kontextzustand, schrittweise Tool-Aufrufe, deren Ergebnisse, stop_reason und Runtime-Config.

Q: Kann man Replay ohne Zugriff auf Production-API machen?
A: Ja. Meist nutzt man gespeicherte Antworten oder mocks, um die Incident-Logik stabil zu reproduzieren.

Q: Wann gilt ein Replay-Case als abgeschlossen?
A: Wenn der Fix im erneuten Replay besteht und dasselbe Szenario im Regression-Set stabil besteht.

Was als Nächstes

Nach Replay-Analysen fügt Incident-Cases in Golden Datasets ein und validiert sie über Regression Testing. Für standardisierte Runs nutzt Eval Harness, und lokale Logik prüft über Unit Testing.