Wie man einen KI-Agenten in Produktion debuggt (Ein Praxisleitfaden)

Inhaltsverzeichnis

Aktualisiert Juni 2026.

TL;DR: Einen Produktions-KI-Agenten zu debuggen heißt vor allem, zu isolieren, welche Schicht versagt hat — Prompt, Tool-Aufruf, Modellausgabe oder Orchestrierung. Ich protokolliere jeden Schritt mit einer Trace-ID, spiele die exakten Eingaben erneut ab und halbiere von dort aus. In meinen Agenten erweisen sich rund 70 % dessen, was wie ein „KI-Bug” aussieht, als Verkabelung: ein fehlerhaftes Tool-Ergebnis, eine abgeschnittene Eingabe, eine stillschweigend verschluckte Ausnahme.

Sicht des Operators: Ich betreibe über 100 Produktions-Agenten — Buchungsabläufe für Pickleland, Content-Pipelines, Posteingangs-Triage. Sie brechen so, wie jede Software bricht, plus ein paar neue Arten. Dies ist der Praxisleitfaden, den ich mir gewünscht hätte: wie man die fehlerhafte Schicht findet, ohne auf eine Wand aus Tokens zu starren.

Wenn ein Agent sich in Produktion fehlerhaft verhält, ist der Instinkt, dem Modell die Schuld zu geben. „Claude hat halluziniert.” Manchmal stimmt das. Meist nicht. Das Modell ist eine Schicht in einem Stapel aus fünf oder sechs, und der Bug steckt weit häufiger in der Schicht, die du geschrieben hast, als in der, die Anthropic ausgeliefert hat. Dieser Beitrag beschreibt die systematische Art, wie ich ihn finde.

Mach jeden Lauf nachverfolgbar, bevor du irgendetwas debuggst

Du kannst nicht debuggen, was du nicht sehen kannst. Das Wirkungsvollste, was du tun kannst — bevor irgendein konkreter Bug auftaucht — ist, jedem Agentenlauf eine Trace-ID anzuhängen und jeden Schritt zu protokollieren, den er macht.

Ein „Schritt” ist alles, was eine Grenze überschreitet: der eingehende Trigger, jeder Modellaufruf (mit dem vollständigen Messages-Array), jeder Tool-Aufruf (mit Argumenten), jedes Tool-Ergebnis und die finale Ausgabe. Protokolliere sie als strukturiertes JSON, indiziert über die Trace-ID.

function logStep(traceId: string, step: string, payload: unknown) {
  console.log(JSON.stringify({
    traceId,
    step,            // "trigger" | "model_call" | "tool_call" | "tool_result" | "output"
    ts: Date.now(),
    payload,
  }));
}

Auf Cloudflare Workers schicke ich diese an eine Queue und in eine Tabelle; lokal gehen sie nach stdout. Die Regel ist absolut: Wenn ein Schritt nicht protokolliert ist, hat er für das Debugging nicht stattgefunden. Das spiegelt die Instrumentierung wider, die ich in dem Agenten-Stack, den ich verwende beschreibe — die Trace-ID ist das Rückgrat, an dem alles andere hängt.

Isoliere die Schicht: Prompt, Tool, Modell oder Orchestrierung

Sobald du eine Trace hast, wird Debugging zu einer Bisektion. Es gibt vier Schichten, und der Bug lebt die meiste Zeit in genau einer von ihnen.

1. Die Eingabeschicht (der häufigste Übeltäter)

Zieh das exakte messages-Array heraus, das in den fehlgeschlagenen Modellaufruf ging. Keine Rekonstruktion — das wörtliche Payload aus dem Log. Dann lies es, wie es ein Fremder tun würde. Die Hälfte meiner Bugs „das Modell hat die Anweisungen ignoriert” sind in Wirklichkeit:

• Ein Tool-Ergebnis, das als "[object Object]" zurückkam, weil etwas falsch in einen String umgewandelt wurde.
• Eine Eingabe, mitten im Satz abgeschnitten, weil sie das Kontextfenster gesprengt hat und ein naiver Slice sie zerschnitten hat.
• Eine Variable, die als undefined interpoliert wurde und den Prompt stillschweigend vergiftet hat.

Wenn die Eingabe falsch ist, hat das Modell seine Arbeit perfekt auf Müll erledigt. Repariere die Verkabelung.

2. Die Tool-Schicht

Wenn die Eingabe sauber aussieht, prüfe, ob ein Tool einen Fehler zurückgegeben hat, den der Agent als Erfolg behandelt hat. Ein Klassiker: Eine API gibt 200 mit einem Body von { "error": "rate limited" } zurück, dein Tool-Wrapper prüft den Body nicht, und der Agent handelt selbstbewusst auf einer Fehlermeldung. Protokolliere Tool-Ergebnisse roh und überprüfe ihre Form.

3. Die Modellschicht

Erst nachdem ich 1 und 2 ausgeschlossen habe, verdächtige ich das Modell. Selbst dann bedeutet „Modell-Bug” meist „mein Prompt ist mehrdeutig”. Nimm die exakte fehlgeschlagene Eingabe, leg sie in ein einmaliges Skript gegen dasselbe Modell und dieselbe Temperatur und schau, ob es sich reproduziert. Wenn ja, ist die Lösung Prompt-Arbeit oder eine strengere Eval, kein hektischer Modellwechsel.

4. Die Orchestrierungsschicht

Wenn ein einzelner Schritt isoliert in Ordnung ist, aber der mehrstufige Lauf fehlschlägt, steckt der Bug in der Übergabe — verlorener Zustand zwischen Schritten, eine Race Condition, ein Retry, der eine nicht-idempotente Aktion erneut ausgeführt hat. Das sind die ekligsten, und ich behandle die Muster in Mehr-Agenten-Orchestrierungsmustern.

Reproduziere Nicht-Determinismus, statt ihn zu bekämpfen

Was Agenten undebugbar erscheinen lässt, ist Nicht-Determinismus: Dieselbe Eingabe erzeugt über Läufe hinweg unterschiedliche Ausgaben. Du kannst ihn zähmen.

Erstens: Fixiere, was du kannst. Setze temperature: 0 während des Debuggings. Es macht Claude nicht vollständig deterministisch, aber es engt die Varianz stark ein, sodass du einen echten Bug von Sampling-Rauschen unterscheiden kannst.

Zweitens: Führe es N-mal aus. Wenn ein Fehler 1 von 20 Läufen auftritt, lass die exakte Eingabe 50-mal laufen und erfasse jede Ausgabe. Jetzt hast du eine Stichprobe, keine Anekdote. Ein Bug, der in 5 % der Fälle feuert, ist ein echter Bug — du brauchst nur Volumen, um ihn zu sehen.

for i in $(seq 1 50); do
  node replay.mjs --trace=abc123 >> runs.jsonl
done
# dann zähle die Fehlschläge
grep -c '"status":"fail"' runs.jsonl

Drittens: Vergleiche die erfolgreichen und die fehlgeschlagenen Läufe. Mit fixierter Temperatur und derselben Eingabe bedeutet ein Unterschied in der Ausgabe einen Unterschied in der Eingabe, den du noch nicht entdeckt hast — ein Zeitstempel im Prompt, ein variierendes Tool-Ergebnis, ein abgerufenes Dokument, das sich geändert hat.

Bau ein Replay-Harness, damit du aufhörst, in Produktion zu debuggen

Debugging durch erneutes Auslösen des Live-Agenten ist langsam und riskant — er versendet echte E-Mails, bucht echte Plätze. Erfasse stattdessen die Trace und spiele sie offline erneut ab.

Das Replay-Harness lädt eine protokollierte Trace, rekonstruiert die exakten Eingaben für jeden beliebigen Schritt und führt nur diesen Schritt erneut gegen das Modell aus. Weil du das vollständige messages-Array protokolliert hast, brauchst du das vorgelagerte System überhaupt nicht. Das verwandelt einen 10-minütigen Produktions-Roundtrip in eine 2-sekündige lokale Schleife und ist die größte Beschleunigung in meinem Debugging-Workflow.

Ein gutes Replay-Harness lässt dich auch mutieren und erneut ausführen: Ändere eine Zeile des System-Prompts, spiele dieselben 50 fehlgeschlagenen Traces erneut ab und schau, wie viele jetzt bestehen. Das ist die Brücke vom Debugging zur Eval — sobald du ein Korpus fehlgeschlagener Traces hast, hast du den Anfang einer Regressions-Suite.

Beobachte die Metriken, die Ausfälle tatsächlich vorhersagen

Manche Fehler werfen nie eine Ausnahme. Der Agent läuft, gibt etwas Plausibles zurück und tut still das Falsche. Um die zu erwischen, beobachtest du Verhaltensmetriken, nicht nur Fehlerraten:

• Tool-Aufruf-Erfolgsrate pro Tool. Ein Rückgang hier geht oft einem sichtbaren Ausfall voraus.
• Gültigkeit des Ausgabeschemas — wie viel % der Ausgaben gegen die erwartete Struktur parsen. Ich validiere jede Ausgabe mit Zod und alarmiere, wenn die Gültigkeit sinkt.
• Schleifenlänge — durchschnittliche Anzahl der Schritte pro Lauf. Ein plötzlicher Anstieg bedeutet meist, dass der Agent in Wiederholungen feststeckt.
• Kosten pro Lauf — eine außer Kontrolle geratene Schleife zeigt sich als Kostenspitze, bevor sie sich als Beschwerde zeigt. (Wenn Kosten zählen, lohnt sich die Haiku-vs-Sonnet-Rechnung.)

Ich verfolge diese genauso wie alles andere — siehe wie ich messe, ob ein KI-Agent tatsächlich funktioniert. Die Metrik, die einen stillen Ausfall erwischt, ist zehn wert, die laute erwischen.

Die 5-Minuten-Triage-Checkliste

Wenn ein Agent bricht und die Uhr läuft, gehe ich diese der Reihe nach durch:

1. Hol die Trace-ID des fehlgeschlagenen Laufs.
2. Lies die exakte Eingabe des fehlgeschlagenen Schritts. Ist sie wohlgeformt? (Löst hier ~50 % der Fälle.)
3. Prüfe die Tool-Ergebnisse in dieser Trace auf als Erfolg getarnte Fehler.
4. Spiele den Schritt offline erneut ab bei temperature: 0. Reproduziert er sich?
5. Wenn er sich reproduziert, ist es ein Prompt-/Modellproblem — beheben und das Trace-Korpus erneut ausführen. Wenn nicht, ist es Nicht-Determinismus oder ein Zustands-/Orchestrierungs-Bug — 50× durchlaufen lassen, um ihn zu charakterisieren.

Disziplinierte Isolation schlägt cleveres Prompting jedes Mal. Das Modell ist selten das Problem; das System drumherum meist schon.

FAQ

Wie debugge ich einen KI-Agenten, der nur manchmal fehlschlägt?

Erfasse die exakte Eingabe aus einer protokollierten Trace und spiele sie über 50-mal bei Temperatur 0 erneut ab. Intermittierende Fehler sind echte Bugs mit niedriger Auslöserate — Volumen verwandelt die Anekdote in eine reproduzierbare Stichprobe, die du vergleichen und beheben kannst.

Steckt der Bug meist im Modell oder in meinem Code?

In meinen Produktions-Agenten sind rund 70 % der scheinbaren „KI-Bugs” Verkabelung: fehlerhafte Tool-Ergebnisse, abgeschnittene Eingaben, verschluckte Ausnahmen oder verlorener Zustand zwischen Schritten. Schließe die Eingabe- und Tool-Schichten aus, bevor du das Modell verdächtigst.

Was ist das Minimum an Protokollierung, das ich zum Debuggen von Agenten brauche?

Eine Trace-ID bei jedem Lauf, plus strukturierte Logs des Triggers, jedes Modellaufrufs (vollständiges Messages-Array), jedes Tool-Aufrufs und seines rohen Ergebnisses und der finalen Ausgabe. Wenn ein Schritt nicht protokolliert ist, kannst du ihn nicht debuggen.

Wie höre ich auf, gegen die Live-Produktion zu debuggen?

Bau ein Replay-Harness, das eine protokollierte Trace lädt und jeden einzelnen Schritt offline mit den erfassten Eingaben erneut ausführt. Es verwandelt einen langsamen, riskanten Produktions-Roundtrip in eine schnelle lokale Schleife und wird zum Samen deiner Regressions-Suite.