Debugging von KI-Agenten: Ihr Dashboard kennt die Kosten, aber nicht die Ursache.

Das Debugging von KI-Agenten beginnt dort, wo Ihr Observability-Dashboard endet. Wenn ein KI-Coding-Agent etwas kaputtmacht und der Lauf bereits abgeschlossen ist, kann das Dashboard Ihnen sagen, was der Lauf gekostet hat (Tokens, Dollar, Latenz), und es schweigt zu der einzigen Frage, die Sie tatsächlich haben: Warum hat der Agent diese Datei geändert? Das Artefakt, das diese Frage beantwortet, ist ein aufgezeichneter Trace, den Sie öffnen, lesen und erneut abspielen können, denn er gibt Ihnen den Lauf zurück, anstatt ihn von außen zu beschreiben.

Das hörte auf, ein seltenes Ereignis zu sein, sobald Agenten echte Arbeit verrichteten. Ein Agent durchläuft ein Repository, bearbeitet mehrere Dateien, führt die Prüfungen aus und meldet Erfolg – alles zwischen zwei Eingabeaufforderungen, die Sie im Abstand von Minuten getippt haben. Wenn eine dieser Bearbeitungen falsch ist, merken Sie es erst später: nachdem das Terminal geschlossen ist, nachdem der Scrollback verschwunden ist, nachdem der Prozess, der sich hätte erklären können, beendet ist. Was als Nächstes passiert, hängt vollständig davon ab, was Sie aufbewahrt haben. Wenn die Antwort ein Kosten-Dashboard ist, steht Ihnen Archäologie bevor. Wenn die Antwort eine Aufzeichnung ist, steht Ihnen das Lesen bevor.

Der Fehler, den Sie nicht reproduzieren können

Hier ist die Sache: Du kommst zum Repository zurück und eine Datei, die du nie jemanden zu bearbeiten gebeten hast, wurde neu geschrieben, gelöscht oder von der Funktion entleert, von der alles andere abhängt. Du fragst den Agenten, was passiert ist; die Sitzung ist geschlossen, und selbst wenn ein Transkript überlebt, ist der Bericht des Agenten über seinen eigenen Lauf eine Rekonstruktion, keine Aufnahme. Also tust du das Naheliegende und führst es erneut aus, und du bekommst einen anderen Lauf. Andere Tool-Aufrufe, andere Änderungen, möglicherweise gar kein Fehler, weil die ursprüngliche Trajektorie vom Sampling, vom Zustand des Repositories und vom Timing abhing. Der Lauf, den du untersuchen musst, existiert nicht mehr.

Es ist schlimmer als nicht reproduzierbar. Es ist nicht reproduzierbar und wird als Erfolg markiert. Ein Lauf endet mit Exit-Code 0, wenn der Agent mit Exit-Code 0 endet, selbst wenn eine Prüfung innerhalb des Laufs mit Exit-Code 1 endete: Die Pipeline kann grün sein, während ein Verifizierungsschritt innerhalb des Laufs fehlgeschlagen ist, und der Exit-Code, dem Sie natürlicherweise vertrauen würden, sagt Ihnen nichts.

Es spielt keine Rolle, welches Modell der Router für den Lauf ausgewählt hat (GLM 5.3 Flash oder etwas anderes): Sobald der Prozess beendet ist, ist auch die Überlegung verschwunden. Die Beweise existierten nur, solange der Lauf aktiv war: die Prompts, die Tool-Aufrufe, die Ausgaben, die Diffs. Wenn nichts sie festgehalten hat, hat „Warum hat es diese Datei geändert?“ keine Antwort. Es gibt nur Theorien.

Das ist die Fehlerart. Sie trennt KI-Codierungsagenten von jedem Werkzeug, das vor ihnen kam: Der Schaden und die Erklärung geschehen am selben Ort, und der Ort schließt sich.

Was misst ein Dashboard, und worüber tritt es hinweg?

Der Instinkt nach einem schlechten Durchlauf ist, das Observability-Dashboard zu öffnen – und das Dashboard wird seinen Job wirklich gut machen. Sein Job ist Traffic: Tokens pro Tag, Kosten pro Modell, Latenz, Fehlerraten. Für Kapazitätsplanung und Abrechnung ist das genau das richtige Instrument, und wenn du Agents in Produktion betreibst, solltest du es offen haben.

Aber deine Frage ist nicht aggregiert. Sie ist singulär und kausal: Warum hat dieser Lauf diese Datei verändert? Aggregation schreitet genau über die Granularität hinweg, die die Antwort liefert. Über Läufe hinweg gemittelt ist der Lauf, der dich interessiert, Rauschen; innerhalb dieses Laufs ist der Tool-Aufruf, der dich interessiert, wieder Rauschen.

Ein Dashboard beschreibt einen Lauf von außen: dass er stattfand, was er wog, was er kostete. Es kann dir den Lauf nicht übergeben, und das „Warum“ ist keine Eigenschaft der Beschreibung. Es ist eine Eigenschaft der Sequenz.

• Was hat der Lauf gekostet? — Kosten-Dashboard beantwortet es vs. aufgezeichneter Trace beantwortet es

• Warum hat der Agent diese Datei geändert? — Kosten-Dashboard Keine Antwort vs. aufgezeichneter Trace Die Änderung, in der Reihenfolge, mit ihrem Diff

• Welcher Check ist in einem grünen Durchlauf fehlgeschlagen? — Kosten-Dashboard: Keine Antwort vs. aufgezeichneter Trace. Der Check mit seinem Exit-Code.

• Kann ich denselben Fehler erneut ausführen? — Kosten-Dashboard: Nein vs. aufgezeichneter Trace: Ja, offline, ohne Kosten.

Die Ebene, die sie beantwortet, liegt darunter: aufgezeichnete Anfrageprotokolle, erfasst während des Laufs, mit jedem gesendeten Prompt, jedem ausgeführten Tool-Aufruf, jeder eingegangenen Antwort, der Reihe nach. Keine Zusammenfassung des Laufs. Der Lauf selbst.

Einen Lauf als Zeitleiste lesen

Mit einer Aufnahme hört Debugging auf, Archäologie zu sein, und wird zum Lesen. {{1}}Archäologie{{/1}} ist das, was man ohne eine betreibt: git reflog, Stash-Einträge, Shell-Historie, die eigene Erinnerung daran, was man früher am Tag angefordert hat. {{2}}Lesen{{/2}} ist das, was man mit einer tut: die Zeitleiste öffnen und scrollen.

Die Zeitleiste stellt den Ablauf in der Reihenfolge dar, in der er sich ereignet hat: der Prompt, der ihn ausgelöst hat, jeder Tool-Aufruf, jede Dateibearbeitung mit ihrem Diff, jede Prüfung, jeder Exit-Code. Eine Momentaufnahme des Dateisystems wird einmal pro Runde erstellt und nicht einmal pro Tool-Aufruf – das genügt, um den Zustand des Repos bei jedem Schritt der Konversation zu sehen, ohne im Rauschen der einzelnen Aufrufe zu ertrinken. Was dies zu Debugging und nicht zu bloßem Stöbern macht, ist die Nachbarschaft: Die Bearbeitung und die Prüfung, die den Fehler aufdeckte, liegen direkt nebeneinander, in der richtigen Reihenfolge, ohne dass dazwischen etwas Raum für Spekulationen bliebe. „Warum“ ist größtenteils eine Eigenschaft der Nachbarschaft.

Ein konkretes Beispiel, einem aufgezeichneten Fix entnommen: 14 Ereignisse, darunter die als +1 -3 angezeigte Dateiänderung und ein fehlgeschlagener Check mit Exit-Code 1. Die Bearbeitung und der dadurch fehlgeschlagene Check stehen im Protokoll nebeneinander. Das ist genau der Unterschied zwischen der Rekonstruktion eines Laufs aus Fragmenten und dem Lesen eines Laufs. Am wichtigsten ist das für Terminal-Coding-Agenten, deren Arbeitsbereich ein Terminal ist, das sich schließt, sobald der Job erledigt ist: Die Zeitleiste ist der Scrollback, der erhalten bleibt.

Aufgezeichnet oder abgeleitet: Was der Trace weiß gegenüber dem, was er ermittelt hat

Eine Zeitleiste verrät dir, was in welcher Reihenfolge geschah. Der Kausalgraph verrät dir, was zu was führte – und die Lücke zwischen den beiden ist der Ort, an dem Vertrauen verdient werden muss.

Der Graph verbindet Ereignisse: diese Bearbeitung, dann dieser fehlgeschlagene Check. Einige dieser Kanten sind aufgezeichnete Fakten: der Tool-Aufruf, der den Diff erzeugt hat, ist direkt in der Trace zu sehen. Andere werden abgeleitet: die Schlussfolgerung des Graphen, dass der Check wegen dieses Diffs fehlgeschlagen ist. orca graph kennzeichnet jede Kante als aufgezeichnet oder abgeleitet und benennt die Regel, die es in beiden Fällen verwendet hat, sodass Sie immer wissen, ob Sie etwas betrachten, das der Lauf getan hat, oder etwas, das das Tool über den Lauf herausgefunden hat.

Diese Unterscheidung ist kein bloßer Anspruch, sondern wird durchgesetzt: inferierte Kanten werden nie in den Trace zurückgeschrieben. Der Trace bleibt eine getreue Aufzeichnung dessen, was geschehen ist; die Inferenz ist eine Sicht darauf, die man einsehen, hinterfragen und auch ablehnen kann. Das ist vor allem dann wichtig, wenn mehr als ein Agent beteiligt ist. Wenn ein Refactoring-Agent und ein Testschreib-Agent dieselben Dateien bearbeiten, ist „welcher Agent das verursacht hat“ genau die Frage, die Multi-Agent-Attributionbeantworten soll. Eine Kante, die sich leise von einer Inferenz zu einer Tatsache befördert, führt dazu, dass man am Ende eine Geschichte debuggt statt eines Laufs.

Es so oft reproduzieren, wie Sie möchten — kostenlos.

Lesen erklärt. Wiederholen beweist. Sobald du eine Hypothese hast (die Prüfung schlug fehl, weil die Bearbeitung den Reset-Aufruf entfernte), möchtest du sie erneut ausführen und beobachten, wie es passiert. Das erneute Ausführen des Live-Agenten bringt dir eine neue Trajektorie und eine neue Rechnung.

Die Aufzeichnung erneut abzuspielen bringt dir denselben Durchlauf: Der Wiederholungslauf erfolgt bei blockiertem Netzwerk, kostet also keine Tokens und hat keine Varianz. Dieselben Ereignisse, jedes Mal, offline. Das ist die Eigenschaft, die das Debugging von Agenten vom Glücksspiel zur Ingenieursarbeit macht: Der Fehler ist deterministisch geworden, und deterministische Fehler werden behoben.

Das Tooling ist auch keine Blackbox. OrcaReplay ist Open Source unter Apache-2.0, und das Trace-Format ist unter CC BY 4.0 lizenziert, sodass man es neu implementieren kann: Ihre Aufzeichnungen sind keinem proprietären Format ausgeliefert, auch unsere nicht. Und es wird getestet, nicht nur vorgeführt: 1393 Tests auf Node 20 und Node 22. Sie können den Quellcode lesen, das Format prüfen und die Testsuite selbst ausführen, bevor Sie ihm die Läufe Ihres Teams anvertrauen.

Das Fazit

Ein Dashboard ist eine Rechnung. Ein aufgezeichneter Trace ist der Lauf. Wenn dein Plan zum Debuggen von KI-Agenten bei einem Kosten-Dashboard endet, hast du keinen Debugging-Plan – du hast ein Abrechnungssystem. Das Dashboard wird dir zwar immer sagen können, was ein Lauf gekostet hat, aber nie, warum der Agent deine Datei gelöscht hat. Denn das „Warum“ lebt in der Sequenz, und die Sequenz existiert nur, wenn du sie gespeichert hast.

Die gesamte Methode besteht aus vier Schritten:

• Erfassen Sie die Läufe.

• Lesen Sie die Zeitleiste.

• Überprüfen Sie die Kanten des Graphen.

Spiele diejenigen, die dir Angst machen, kostenlos erneut, so oft du möchtest.

Quellenhinweis: Alle Zahlen in diesem Artikel stammen von Herstellern – sowohl aus unserem eigenen Produkt als auch aus dem OrcaReplay-Repository und dessen Dokumentation: das Exit-Code-Verhalten eines Laufs, der aufgezeichnete Fix mit 14 Ereignissen samt +1 -3-Diff und Exit-1-Prüfung, die Kantenbeschriftung im Orca-Graphen, der Snapshot-Rhythmus von einem Snapshot pro Zug, Offline-Replay mit blockiertem Netzwerk sowie die 1393 Tests umfassende Testsuite unter Node 20 und Node 22. In diesem Artikel werden keinerlei Messungen Dritter zitiert. Die Testsuite mit 1393 Tests ist die eine Behauptung, die Sie selbst überprüfen können, indem Sie das Repository klonen und ausführen. Alle Angaben wurden zuletzt am 04.09.2026 geprüft.