Der Agent, der feststeckte: Echte Fehler in der Multi-Agenten-Orchestrierung

Das Format der KI-Erfolgsgeschichte kennt jeder: Prompt rein, fertiger Code raus, Entwickler beeindruckt. Das Gegenstück — der Fehlschlag — kommt selten vor. Dabei ist genau da der Lerneffekt am größten.

Hier sind vier echte Fehler aus meiner Multi-Agenten-Arbeit. Kein Schönreden, kein nachträgliches „daraus hab ich gelernt”-Framing, das mich klüger aussehen lässt als ich war. Nur: was ist schiefgelaufen. (Die Session, in der die meisten dieser Fehler passiert sind — meine erste Million-Token-Session — ist separat dokumentiert.)

Fehler 1: Der visuelle Refiner, der einfach nicht aufhörte

In einer Session — der 16-stündigen, die 187 $ gekostet hat — lief ein visueller Refiner-Agent auf einer deployed Web-App. Seine Aufgabe: Screenshot machen, visuelle Verbesserungen erkennen, Änderungen umsetzen, neuen Screenshot machen, prüfen ob’s stimmt, fertig.

Er war nie fertig.

Der Agent machte einen Screenshot. Fand Verbesserungen. Setzte sie um. Machte einen neuen Screenshot. Fand neue Verbesserungen im aktualisierten Screenshot. Mehr Änderungen. Und so weiter. Bei jedem Durchlauf hat er wirklich echte Dinge gefunden — aber die Messlatte wanderte mit. Eine Änderung, die ein Problem löste, erzeugte eine leicht andere visuelle Inkonsistenz. Die fand der Agent und wollte sie ebenfalls fixen.

Ich hab ihn abgewürgt, als mir auffiel, dass der Token-Verbrauch munter weiter stieg, ohne dass irgendwas committed wurde.

Was ich danach geändert habe: explizite Abnahmekriterien für visuelle Refiner. Nicht „sieh zu, dass es gut aussieht”, sondern „Header-Hintergrund #1a1a1a, Button-Radius 6px, Card-Padding 16px.” Konkret und prüfbar. Dazu: Timeouts. Jeder visuelle Refiner, der nach N Iterationen nicht fertig ist, wird gestoppt — mit dem, was er bis dahin produziert hat.

Die Erkenntnis war nicht „benutz keine visuellen Refiner”. Sondern: offene Qualitätsziele sind unendlich. Du musst definieren, wann etwas fertig ist.

Fehler 2: Das Shell-Script, das mein Terminal gefressen hat

Dieser Fehler hat Stunden gedauert zu diagnostizieren — und war am Ende peinlich simpel.

Ich hatte ein Status-Script eingerichtet: eine Terminal-Prompt-Erweiterung, die Modellname, Session-Kosten und Kontext-Auslastung direkt im Prompt anzeigte. Praktisch, sieht professionell aus. Mehrere Sessions lang lief es problemlos.

Dann kam Session 7. Terminal-Befehle hingen. Nicht abstürzen — hängen. git status lief ins Leere. ls hing. Selbst grundlegende Shell-Utilities froren ein.

Ich habe Claude Code beschuldigt. Die MCP-Server-Konfiguration. Speicherprobleme. Den Session-Kontext hab ich zweimal komplett neu aufgebaut.

Des Rätsels Lösung: Das Status-Script hat stdout von Kind-Prozessen abgefangen, um Kosten und Kontext-Daten zu extrahieren — indem es die Subprocess-Ausführung ummantelt hat. Dieser Wrapper hat gestört, wie Claude Code seine eigenen Kind-Prozesse startet. Wenn der Agent einen Bash-Befehl ausführen wollte, wurde die Ausgabe vom Status-Script abgefangen, das auf bestimmte Muster wartete — die nie kamen — und den Prozess so endlos blockierte.

Fix: stdout-Capture aus dem Status-Script raus. Separate Log-Dateien statt abgefangener Subprocesses.

Die Erkenntnis: Terminal-Erweiterungen und KI-Agenten-Tooling können auf Weisen interagieren, die absolut unsichtbar sind — bis alles auf einmal kaputt ist. Teste beides zusammen, bevor du in einer echten Session darauf angewiesen bist.

Fehler 3: Die MCP-Berechtigungsmauer

Ich hatte spezialisierte Agenten für verschiedene Tech-Stacks gebaut: einen für Kotlin, einen für TypeScript, einen für React, einen für DevOps. Jeder hatte tiefes Domänenwissen in seinen Anweisungen. Die Spezialisierung war real und wertvoll — der Kotlin-Agent hat tatsächlich bessere Entscheidungen über Kotlin-Code getroffen als ein Allzweck-Agent.

Dann wollte ich einen spezialisierten Agenten ein Jira-Ticket erstellen lassen.

Fehler. Der spezialisierte Agent hatte keinen Zugriff auf MCP-Tools. Er konnte nur die eingebauten Claude Code Tools nutzen. Jira-Integration, GitHub-Integration, Web-Fetching — alles das erfordert MCP-Tool-Zugriff, der nur für Allzweck-Agenten verfügbar war.

Die gesamte Architektur brauchte einen Workaround. Spezialisierte Agenten können alles in ihrer Domäne — aber alles, was externe Integrationen braucht, müssen sie an einen Allzweck-Agenten übergeben. Das bedeutet: Task-Routing-Logik. Erkennen, ob eine Aufgabe MCP-Tools erfordert, und wenn ja, an einen Allzweck-Wrapper eskalieren.

Die Erkenntnis: Versteh das Berechtigungsmodell deines Tools, bevor du deine Agenten-Architektur entwirfst. Die Einschränkungen sind nicht immer offensichtlich — und sie mitten in einem laufenden Workflow zu entdecken ist mühsam.

Fehler 4: Die Schleife, die nicht wusste, dass sie eine Schleife war

In einer Session mit mehreren Agenten in einer Team-Struktur bekam ein Agent eine Aufgabe, fing an zu arbeiten, lief in einen Fehler, meldete ihn an den Orchestrator, bekam dieselbe Aufgabe mit leicht anderem Framing zurück, lief in denselben Fehler, meldete ihn wieder.

Das ging so mehrere Zyklen lang, bis ich es bemerkte.

Der Orchestrator empfing den Fehlerbericht und stellte die Aufgabe erneut in die Warteschlange. Er erkannte nicht, dass der Fehler strukturell war — eine fehlende Abhängigkeit, die sich durch nochmaliges Versuchen nicht beheben ließ — und kein vorübergehender Fehler. Die Retry-Logik funktionierte wie vorgesehen. Das Design war falsch.

Fix: Fehlerklassifizierung. Vorübergehende Fehler (Netzwerk-Timeouts, temporäre Ausfälle) werden wiederholt. Strukturelle Fehler (fehlende Konfiguration, Abhängigkeitsprobleme, fehlende Berechtigungen) werden sofort eskaliert statt wiederholt. Der Orchestrator brauchte eine Möglichkeit, „nochmal versuchen” von „ich komme ohne Eingriff nicht weiter” zu unterscheiden.

Was alle vier gemeinsam haben

Bei einem einzelnen Agenten ist ein Fehler debuggbar. Ein Agent, eine Aufgabe, ein Fehler — du liest die Ausgabe und weißt, was passiert ist.

Bei mehreren Agenten entstehen Fehler aus dem Zusammenspiel. Aus Timing-Problemen. Aus Berechtigungskonflikten, die kein einzelner Agent sehen kann, weil jeder nur seine eigene Perspektive hat. Der Fehler aus Fehler 4 war für keinen der beteiligten Agenten sichtbar. Der Orchestrator dachte, er behandelt den Fehler korrekt. Der Worker dachte, er meldet den Fehler korrekt. Beide hatten aus ihrer Sicht recht. Das System war falsch.

Was Multi-Agenten-Systeme erfordern, ist näher an verteilten Systemen als an Einzelagenten-Prompt-Design. Du brauchst Timeouts, Circuit Breaker, Fehlerklassifizierung, definierte Fehlermodi und Eskalationspfade — nicht weil die Agenten schlecht sind, sondern weil jedes System mit mehreren interagierenden Komponenten auf Weisen scheitert, die keine einzelne Komponente selbst erkennen oder beheben kann.

Keiner meiner Agenten hat dumm versagt. Sie haben auf eine Art versagt, die aus ihrer jeweiligen Perspektive völlig rational war. Die Fehler waren architektonisch. (Die 18-Agenten-Architektur, aus der diese Fehler entstanden sind, hat ihren eigenen Post — inklusive der Design-Entscheidungen, die trotzdem funktioniert haben.)