Agent hängt: So findest du die Ursache und reparierst deinen KI-Agenten

Was „der Agent hängt“ bedeutet, einfach erklärt

Das Auto ist liegengeblieben. Jetzt gibt es zwei Typen Mensch. Der erste haut auf die Motorhaube, schreit „na komm schon!“ und dreht zum zehnten Mal den Schlüssel in der Hoffnung, dass es „von allein anspringt“. Der zweite macht die Haube auf, leuchtet mit der Taschenlampe rein - und da ist einfach der Sprit alle.

Mit dem KI-Agenten ist es genau die gleiche Geschichte. Er „hängt“ - dreht sich im Kreis, läuft in einer Schleife, streitet oder redet Quatsch. Der Anfänger haut auf die Motorhaube: fragt das Gleiche mit ein paar anderen Worten nochmal, wird sauer und löscht am Ende das ganze Projekt. Der Vibecoder macht die Haube auf: stellt eine Diagnose, findet die Ursache und behandelt genau die. Der Unterschied: Stunden an Zeit und ein Haufen verbrannter Tokens.

Warum du KI-Agent-Diagnose lernen solltest

Weil der Agent hängen wird. Das ist so unausweichlich wie Stau am Freitagabend. Die einzige Frage ist: Was machst du in dem Moment - panisch werden oder reparieren?

• Kein Diagnose-Skill - du verbrennst Tokens (also Geld) mit sinnlosen Nachfragen.
• Du verlierst Stunden damit, mit der KI zu streiten, obwohl die Ursache in einer Minute zu finden wäre.
• In Panik bist du fähig, funktionierenden Code zu löschen, obwohl die Reparatur nur einen Handgriff gebraucht hätte.

Diese Lektion ist dein „Erste-Hilfe-Kasten“. Im Skill ECC ECC (Engineering-Centric Coding) - eine Sammlung fortgeschrittener Arbeitstechniken für den Umgang mit Agenten. agent-introspection-debugging ist der „Selbstdiagnose-Skill“: Er bringt dem Agenten bei, seine Fehler Schritt für Schritt zu zerlegen, bevor er aufgibt. heißt er agent-introspection-debugging - eine strukturierte Fehleranalyse statt blinder Wiederholungen. Jetzt zerlegen wir ihn in einfache Schritte.

So reparierst du den Agenten: 4 Schritte statt Panik

Merk dir eine Regel: Wiederhol nicht dreimal das Gleiche mit nur ein paar anderen Wörtern. Genau das ist das häufigste Antipattern. Willst du ein Ergebnis, geh durch die vier Phasen. Jede dauert ein paar Minuten, und zusammen sparen sie dir Stunden.

Schritt 1. Halt den Fehler fest - mach ein Foto vom Unfallort

Bevor du irgendwas anfasst - schreib auf, was überhaupt passiert ist. Nicht im Kopf, sondern in Worten:

• Was hat der Agent im Moment des Defekts versucht?
• Welcher Fehler kam hoch (genauer Text, falls vorhanden)?
• Was war der letzte erfolgreiche Schritt?
• Welche Aktion wiederholt sich im Kreis?
• Wovon geht der Agent gerade aus - wo glaubt er zu sein (Ordner, Branch, welche Dateien existieren)?

Schritt 2. Finde die Ursache - stell eine Diagnose

Jetzt ordnest du das Symptom einer typischen Ursache zu. Es sind nicht viele, und man erkennt sie auf den ersten Blick:

Und hier vier Filter-Fragen - sie schneiden Überflüssiges weg und benennen den Defekt-Typ:

• Ist es Logik (der Agent denkt falsch), Zustand (die Welt ist nicht so, wie er denkt), Umgebung (etwas draußen funktioniert nicht) oder Regel (man hat ihm keine Anweisung gegeben)?
• Hat er das Ziel verloren und schraubt vielleicht an der falschen Aufgabe?
• Ist der Fehler dauerhaft oder zufällig - kurz aufgeblitzt und wieder weg?
• Welche kleinste Aktion bestätigt, dass meine Vermutung stimmt?

Schritt 3. Behandle mit einer kleinen Aktion

Kein „alles neu schreiben“. Nimm die kleinste Aktion, die das Bild verändert:

Schritt 4. Kurzer Bericht, damit du nicht nochmal in dieselbe Falle trittst

Hör nicht bei „fertig, repariert“ auf. Schreib kurz auf: was kaputt war, was die Ursache war, was ich gemacht habe, woran ich gemerkt habe, dass es besser wurde. Das ist deine Versicherung. Beim nächsten Mal erkennst du das Pattern in Sekunden statt in einer halben Stunde.

Wenn nicht das Modell hängt, sondern die Hülle (der Harness)

Manchmal ist es trickreicher. Das Modell selbst ist clever - du hast es „live“ getestet, und alles war ok. Aber innerhalb deiner App hängt es. Heißt: Nicht der Koch macht Mist, sondern die Küche um ihn herum - die Hülle, auch Harness genannt. In ECC behandelt das der Skill agent-architecture-audit.

Die Idee ist simpel. Zwischen dem Gehirn des Modells und dem, was du siehst, liegen viele Schichten: System-Prompt, History, Langzeitgedächtnis, Tool-Auswahl, Tool-Ausführung, das Lesen des Ergebnisses, das Rendern der Antwort. Und jede einzelne kann eine gute Antwort unbemerkt verderben.

Der Harness Harness (Hülle) - die gesamte Verkabelung rund um das Modell: Tools, Gedächtnis, Regeln, Ausgabeformat. Das Modell ist für alle gleich, aber die Hülle hat jede App für sich - und genau sie ist am häufigsten am „Hängen“ schuld. geht auf ein paar typische Arten kaputt:

Hier ein paar schnelle Indikator-Fragen. Schon ein einziges „ja“ heißt: Grab genau dort.

• Kann der Agent ein Pflicht-Tool überspringen und trotzdem antworten? Dann lebt die Regel nur im Text, nicht im Code.
• Taucht in neuen Gesprächen alter Inhalt auf? Das Gedächtnis ist verunreinigt.
• Liegt dasselbe gleichzeitig im Prompt, im Gedächtnis und in der History? Doppelung müllt den Tisch zu.
• Unterscheidet sich die Antwort zwischen „intern“ und „auf dem Bildschirm“? Irgendwas verdirbt die Ausgabe unterwegs.

Beispiel aus dem echten Leben: der Agent repariert das gesunde Bein

Du baust einen Telegram-Bot. Du bittest den Agenten „repariere das Versenden von Nachrichten“. Er fummelt munter am Code, meldet „fertig!“. Du checkst - Stille. Du bittest nochmal - und er geht an dieselbe Stelle und schreibt sie mit anderen Worten um. Und nochmal. Und nochmal. Die Tokens schmelzen, der Bot schweigt, du bist kurz vorm Durchdrehen.

Die Wahrheit ist aber: Der Bot lief nicht, weil der Server selbst gar nicht an war (erinnerst du dich an die Ursache „Verbindung abgelehnt“?). Der Agent hat Code repariert, dem es eh gut ging - er hat das gesunde Bein behandelt, weil er kein einziges Mal die Realität geprüft hat.

So lenkst du ihn beim ersten Anlauf auf den richtigen Weg:

Stopp. Schreib den Code nicht neu. Mach erst eine Diagnose Schritt für Schritt:

Beschreib in Worten: was genau du versucht hast und welcher Fehler hochkam.
Nenn den letzten Schritt, der sicher funktioniert hat.
Prüf die Realität, nicht dein Gedächtnis: läuft der Server,
in welchem Ordner bin ich, in welchem Branch, welche Dateien existieren wirklich.
Ordne das Symptom einer Ursache zu: ist es Logik, Zustand, Umgebung
oder fehlt eine Regel? Nenn die eine wahrscheinlichste Ursache.
Schlag die kleinste Aktion vor, die diese Ursache beweist.
Mach nur die. Den restlichen Code fass nicht an.
Am Ende ein kurzer Bericht: was kaputt war, die Ursache, was du gemacht hast,
woran man merkt, dass es besser wurde.

Häufige Fehler beim Debuggen eines Agenten

• Auf die Motorhaube hauen. Das Gleiche mit anderen Worten wiederholen - das Haupt-Antipattern. Erst die Diagnose.
• Die falsche Krankheit behandeln. Der Agent fummelt am Code, dabei liegt das Problem am ausgeschalteten Server. Prüf die Realität.
• Dem Gedächtnis des Agenten glauben. Er „erinnert sich“ an eine Datei, die es nicht gibt. Schau, was wirklich auf der Platte ist.
• Sofort alles löschen. Eine kleine Aktion schlägt fast immer das „schreiben wir neu“.
• Zuerst das Modell beschuldigen. Lief im Playground, bei dir aber nicht - grab in der Hülle, nicht im Modell.
• Sich still über „repariert“ freuen. Ohne kurzen Bericht tappst du in einer Stunde wieder in dieselbe Falle.