Warum Ihr AutoGen-Agent in Endlosschleifen hängen bleibt – und wie Sie das Problem beheben können

Vor dem Debuggen einer AutoGen-Schleife ist eine wichtige Plattformänderung zu beachten. Seit September 2026 befindet sich das offizielle AutoGen-Repository im Wartungsmodus: Es werden voraussichtlich Wartungsarbeiten durchgeführt, aber keine neuen Funktionen mehr bereitgestellt. Microsoft empfiehlt für neue Projekte das Microsoft Agent Framework. Im offiziellen AutoGen-Repository wird weiterhin Python 0.7.5 als aktuelle stabile Version angegeben. Microsoft hat am 25. August 2026 einen aktualisierten Migrationsleitfaden für die Migration von AutoGen zum Agent Framework veröffentlicht. Wenn Sie AutoGen bereits produktiv einsetzen, sind die unten beschriebenen Techniken zur Fehlerbehebung weiterhin direkt anwendbar. Weitere Informationen finden Sie im offiziellen AutoGen-Repository , in den offiziellen AutoGen-Releases und im AutoGen-Migrationsleitfaden von Microsoft .

Ein AutoGen-Agent scheint sich aus einem von fünf Gründen in einer Endlosschleife zu befinden: Der Durchlauf hat keine zuverlässige Abbruchbedingung, die Richtlinie für den nächsten Sprecher wählt immer wieder einen unproduktiven Teilnehmer aus, ein Tool-Aufruf erzeugt keinen sichtbaren Fortschritt, Agenten schieben die Arbeit hin und her oder die Anwendung stellt immer wieder einen veralteten Zustand wieder her. Die schnellste Lösung besteht nicht darin, jede Ansage neu zu schreiben. Identifizieren Sie zunächst die tatsächliche Schleife, fügen Sie dann einen harten Abbruch ein und reparieren Sie anschließend den fehlerhaften Übergang.

Kurzdiagnose: Um welche Art von Schleife handelt es sich?

1. Fügen Sie einen harten Stopp ein, bevor Sie irgendetwas anderes debuggen.

AutoGen AgentChat bietet integrierte Beendigungsbedingungen, um Teams voneinander abzugrenzen. Die stabile Dokumentation enthält Informationen zu den Beendigungsbedingungen . MaxMessageTerminationWeitere Informationen finden Sie in TextMentionTerminationder offiziellen AutoGen -Dokumentation .TokenUsageTerminationTimeoutTerminationHandoffTerminationSourceMatchTerminationExternalTerminationStopMessageTerminationTextMessageTerminationFunctionCallTerminationFunctionalTermination

Für die meisten Produktionsabläufe empfiehlt sich eine semantische Abschlussbedingung und eine unabhängige Sicherheitsgrenze. Der wichtige Operator ist üblicherweise „ODER“, da der Lauf gestoppt werden soll, sobald die Aufgabe regulär abgeschlossen ist oder die Sicherheitsgrenze erreicht wurde.

from autogen_agentchat.conditions import (
    MaxMessageTermination,
    TextMentionTermination,
)

done = TextMentionTermination("TERMINATE")
safety_cap = MaxMessageTermination(max_messages=25)

termination = done | safety_cap

Ein häufiger Fehler ist, sich ausschließlich auf „TESTINATE, wenn fertig“ zu verlassen. Dadurch wird die Korrektheit dem Modellverhalten überlassen. Ein weiterer Fehler ist die Kombination von Bedingungen, &wenn eigentlich „Stopp bei einer der beiden Bedingungen“ gemeint ist. AutoGen unterstützt sowohl UND- als auch ODER-Verknüpfungen; wählen Sie die Semantik daher bewusst.

Was dadurch behoben wird

• Ein Team, das niemals die erwartete Abschlussphrase produziert.
• Ein Selektor, der immer wieder einen anderen Sprecher findet, obwohl keine sinnvolle Arbeit mehr ansteht.
• Eine Übergabekette ohne natürliches Ende.
• Ein unerwartetes Modell- oder Werkzeugverhalten, das ansonsten unbegrenzte Umdrehungen verursachen würde.

Ein Grenzwert ist ein Schutzschalter, kein Beweis für die Korrektheit des Workflows. Wenn der Lauf aufgrund des Grenzwerts immer wieder abbricht, liegt weiterhin ein Logikfehler vor, der behoben werden muss.

2. Die Vervollständigung sollte maschinenlesbar sein, nicht nur konversationell.

Das stärkste Beendigungssignal ist eines, das Ihre Anwendung ohne Interpretation des Textes erkennen kann. Wenn der Workflow ein eindeutiges Erfolgsereignis aufweist, verwenden Sie die am besten passende Beendigungsbedingung. Beispielsweise kann eine bestimmte Übergabe mit `<pre>` HandoffTermination, der Abschluss eines bestimmten Tools mit `<pre>` FunctionCallTerminationund benutzerdefinierte Logik mit `<pre>` erkannt werden FunctionalTermination.

Wenn Sie diese Methode verwenden TextMentionTermination("TERMINATE"), machen Sie die Verantwortlichkeiten klar: Welcher Akteur darf die Fertigstellung erklären und unter welcher verifizierten Bedingung? Vermeiden Sie vage Anweisungen wie „Fahre fort, bis die Bedingung erfüllt ist“. Solche Anweisungen können zu endlosen Korrektur- und Überarbeitungsprozessen führen, da „erfüllt“ keine klar definierte Grenze hat.

Ein sinnvoller Abschlussvertrag ist konkret: „Der Prüfer sendet TERMINATE erst dann, wenn der Entwurf alle drei erforderlichen Abschnitte enthält und keine offenen Blocker mehr vorhanden sind.“ Noch besser ist es, wenn der Prüfer einen strukturierten Zustand erzeugt, den die Anwendung überprüfen kann.

3. Korrigieren Sie das SelectorGroupChat-Routing, bevor Sie alle Agentenaufforderungen neu schreiben.

SelectorGroupChatAutoGen verwendet ein Modell, um den nächsten Sprecher aus dem gemeinsamen Gesprächskontext auszuwählen. Die Dokumentation weist darauf hin, dass die Namen und Beschreibungen der Teilnehmer wichtig sind, da sie bei der Sprecherauswahl verwendet werden. Standardmäßig wird nicht wiederholt derselbe Sprecher ausgewählt, es sei denn, er ist der einzige verfügbare Agent. allow_repeated_speaker=TrueDieses Verhalten kann jedoch geändert werden. AutoGen bietet außerdem Funktionen selector_func, candidate_funcdie eine präzisere Steuerung ermöglichen. Weitere Informationen finden Sie in der offiziellen Dokumentation von SelectorGroupChat .

Falls immer wieder derselbe Teilnehmer ausgewählt wird, überprüfen Sie Folgendes der Reihe nach:

• Agentenbeschreibungen: Jede Beschreibung sollte die Funktion des Agenten und den Zeitpunkt seiner Auswahl angeben. Überschneidende Beschreibungen führen zu instabilem Routing.
• Selektor-Aufforderung: Halten Sie die Routing-Regeln kurz genug, damit das Modell zuverlässig angewendet werden kann. Die AutoGen-Dokumentation empfiehlt ausdrücklich die Verwendung eines benutzerdefinierten Selektors, wenn die Aufforderung viele Bedingungen enthält.
• Wiederholte Lautsprechereinstellung: Diese Option sollte allow_repeated_speakernur dann deaktiviert werden, wenn aufeinanderfolgende Durchgänge wirklich erforderlich sind.
• Kandidatenbeschränkung: Wenn nach einem bestimmten Zustand nur noch zwei Agenten gültig sind, wird die Kandidatenmenge eingeschränkt, anstatt das Modell aufzufordern, aus allen Teilnehmern auszuwählen.
• Deterministische Übergänge: Anwendung, selector_funcwenn der Arbeitsablauf eigentlich ein als Konversation getarnter Zustandsautomat ist.

Der entscheidende Unterschied ist einfach: Verwenden Sie die LLM-basierte Sprecherauswahl, wenn der nächste Sprecher tatsächlich eine semantische Beurteilung erfordert. Verwenden Sie deterministisches Routing, wenn der nächste Sprecher durch den Workflow-Status vorgegeben ist.

4. Wiederholte Werkzeugaufrufe vermeiden, indem der Fortschritt sichtbar gemacht wird.

In der aktuellen Version von AgentChat AssistantAgentgibt es einen max_tool_iterationsParameter dafür. Laut der stabilen API-Dokumentation ist der Standardwert 1. Wird dieser Wert erhöht, kann der Agent so lange weitere Werkzeugaufrufe nacheinander durchführen, bis das Modell eine Textantwort zurückgibt oder der Maximalwert erreicht ist. Das bedeutet, dass ein einzelner Agentenlauf durch diese Einstellung begrenzt ist. Derselbe Agent kann jedoch von einem Team erneut ausgewählt werden und dasselbe fehlgeschlagene Werkzeugmuster in mehreren Runden wiederholen. Siehe die offizielle AssistantAgent-API-Referenz .

agent = AssistantAgent(
    name="worker",
    model_client=model_client,
    tools=[lookup_tool],
    max_tool_iterations=3,
)

Wenn dasselbe Werkzeug und dieselben Argumente wiederholt verwendet werden, begrenzt die Reduzierung des Iterationslimits lediglich den Schaden. Die eigentliche Lösung liegt üblicherweise im Werkzeugvertrag. Das Modell benötigt ausreichend Informationen, um festzustellen, ob der Aufruf erfolgreich war, dauerhaft fehlgeschlagen ist, vorübergehend fehlgeschlagen ist oder keine neuen Informationen geliefert hat.

Bevorzugen Sie ein kompaktes, explizites Ergebnis wie beispielsweise:

{
    "status": "no_new_data",
    "query": "customer_123",
    "retryable": false,
    "reason": "record already checked",
    "next_action": "return_to_planner"
}

Das ist aussagekräftiger als eine allgemeine Meldung wie „Kein Ergebnis“, da das Modell erkennt, dass ein wiederholter Aufruf keinen Fortschritt darstellt. Bei Tools mit Seiteneffekten sollte zudem Idempotenz auf Anwendungsebene implementiert werden, damit ein wiederholter Aufruf nicht wiederholt dasselbe Ticket, dieselbe Zahlung, dieselbe Nachricht oder dieselbe Datenbankänderung erzeugt.

Prüfen Sie auch die parallelen Toolaufrufe.

Die stabile AssistantAgentReferenz weist darauf hin, dass mehrere Werkzeugaufrufe gleichzeitig ausgeführt werden können und dass parallele Werkzeugaufrufe in unterstützten Modellclients deaktiviert werden können. Sie warnt außerdem davor, dass bei mehreren erkannten Übergaben nur die erste ausgeführt wird, und empfiehlt, parallele Werkzeugaufrufe zu deaktivieren, um dies zu vermeiden. Wenn Ihr Workflow strikte Zustandsübergänge mit jeweils einer Aktion voraussetzt, können parallele Aufrufe die Nachvollziehbarkeit des resultierenden Zustands erschweren.

5. Unterbrecht das Ping-Pong-Spiel in Teams im Swarm-Stil.

Ein Übergabeprozess sieht üblicherweise so aus: Agent A entscheidet, dass Agent B besser geeignet ist, Agent B erkennt unvollständigen Kontext und sendet die Aufgabe zurück, und beide Entscheidungen bleiben lokal unbegrenzt sinnvoll. Das Problem ist nicht, dass eines der Modelle „falsch“ wäre. Der Übergabestrategie fehlt es an Zuständigkeit und einem Endzustand.

Das Problem lässt sich beheben, indem jeder Übergabe eine eindeutige Bedingung und eine Regel für den Fall hinzugefügt wird, dass das Ziel keinen Fortschritt erzielen kann. Bei benutzerinteraktiven Workflows HandoffTermination(target="user")ist vorgesehen, das Team zu stoppen, sobald die Kontrolle an die Anwendung oder Person zurückgegeben werden soll. Die Dokumentation von AutoGen zum Thema „Mensch-in-the-Loop“ erläutert zudem, dass Swarm-Workflows nach einer Benutzerübergabe ein bewusstes Wiederaufnahmeverhalten benötigen. Siehe die offizielle Dokumentation zum Thema „Mensch-in-the-Loop“ .

Ein guter Übergabevertrag beinhaltet:

• die genauen Fähigkeiten, die das Ziel besitzt;
• die Beweise, die die Übergabe rechtfertigen;
• was das Ziel zurückgeben soll, wenn es erfolgreich ist;
• was das Ziel tun sollte, wenn erforderliche Informationen fehlen;
• ein Verbot, die Aufgabe unverändert zurückzusenden.

6. GraphFlow-Zyklen sollten als echte Schleifen behandelt werden, die explizite Ausgänge benötigen.

GraphFlowUnterstützt werden bewusste Zyklen, bedingte Verzweigungen und Schleifenausstiege. Die stabile API definiert Schleifen nur dann als gültig, wenn eine Bedingung existiert, die die Schleife schließlich verlässt, und der Builder die Graphstruktur validiert. Sie ist außerdem als experimentell gekennzeichnet. Eine strukturell gültige Schleife kann dennoch zu lange laufen, wenn die Abbruchbedingung logisch nicht erreichbar ist. Daher sollte eine unabhängige Abbruchbedingung oder ein Durchlauflimit implementiert werden. Weitere Informationen finden Sie in der offiziellen API-Referenz des AutoGen-Teams .

Dies ist besonders relevant bei Modellen mit der Struktur „Autor → Prüfer → Autor“. Wenn der Prüfer angewiesen wird, „so lange zu verbessern, bis es perfekt ist“, wird das Abbruchkriterium möglicherweise nie erfüllt. Ersetzen Sie subjektive Perfektion durch eine klare Bewertungsmatrix, z. B. Vorhandensein der erforderlichen Abschnitte, bestandene Validierungsprüfungen, keine kritischen Fehler und Erreichen der maximalen Anzahl an Überarbeitungen.

7. Zustand zurücksetzen, wenn die nächste Aufgabe nicht relevant ist.

AgentChat-Agenten und -Teams sind zustandsbehaftet. Laut der stabilen Dokumentation von AutoGen behält das Team den Gesprächskontext über mehrere Ausführungen hinweg bei, sodass zusammenhängende Aufgaben fortgesetzt werden können. Außerdem ermöglicht es, reset()den Team- und Teilnehmerstatus übersichtlich darzustellen. Dieses Verhalten ist zwar für die Fortsetzung hilfreich, kann aber wie eine Schleife wirken, wenn eine nicht zusammenhängende Aufgabe alten Kontext, unvollständige Delegation oder vorherige Annahmen übernimmt.

await team.reset()
result = await team.run(task=new_unrelated_task)

Die stabile Agenten-API weist Anrufer außerdem darauf hin, bei jedem Anruf nur neue Nachrichten zu übermitteln, anstatt den gesamten Gesprächsverlauf manuell erneut abzuspielen. Das erneute Einfügen des gesamten Verlaufs, während der Agent gleichzeitig den Status verwaltet, kann zu Kontextduplizierung und wiederholtem Verhalten führen.

8. Protokollieren Sie den Übergang, nicht nur den Endtext.

Wenn eine Schleife schwer nachzuvollziehen ist, sollten Sie für jeden Durchlauf genügend Informationen protokollieren, um vier Fragen zu beantworten: Wer hat gehandelt? Warum wurde diese Person ausgewählt? Welche Aktion wurde versucht? Und was hat sich danach geändert? AutoGen bietet Unterstützung für Tracing und Observability. Die stabile Tracing-Anleitung zeigt, wie AgentChat-Teams verfolgt werden. Weitere Informationen finden Sie in der offiziellen AutoGen-Dokumentation zum Tracing .

Mindestens protokollieren:

• Lauf-ID und Abbiegenummer;
• Nachrichtenquelle und Nachrichtentyp;
• ausgewählter Redner und verfügbare Kandidaten;
• Werkzeugname plus Hash oder normalisierte Form der Argumente;
• Werkzeugstatus und ob sich der Zustand geändert hat;
• Übergabe von Quelle und Ziel;
• Ergebnis der Abbruchbedingung;
• TaskResult.stop_reasonwenn der Lauf endet.

Eine sehr effektive Diagnosemethode ist die Erkennung von „gleicher Aktion, gleichem Zustand“. Ruft derselbe Agent dasselbe Tool mit identischen Argumenten auf und ändert sich der gemeinsame Zustandshash über mehrere Durchläufe nicht, wird der Lauf abgebrochen und als Endlosschleife markiert. Diese Prüfung ist in Ihrer Anwendungslogik implementiert und keine integrierte AutoGen-Funktion. Sie deckt jedoch eine Fehlerklasse auf, die durch Token- oder Nachrichtenlimits erst im Nachhinein erkannt wird.

Eine praktische, sichere Ausgangsbasis

Für eine bestehende AutoGen AgentChat-Anwendung ist eine konservative Ausgangsbasis:

• Konfigurieren Sie immer eine harte Nachricht, einen Turn, ein Timeout oder eine Token-Obergrenze.
• Kombinieren Sie diese Obergrenze mit einer aussagekräftigen Abbruchbedingung, indem Sie ein ODER verwenden, bei dem die Ausführung abgebrochen werden soll.
• Halten Sie die max_tool_iterationsAnzahl der Arbeitsschritte gering, es sei denn, der Anwender benötigt tatsächlich eine mehrstufige Werkzeugsequenz.
• Die Tool-Ergebnisse sollen strukturiert zurückgegeben werden, wobei zwischen Erfolg, keinem Fortschritt, wiederholbarem Fehler und permanentem Fehler unterschieden wird.
• Wiederholte Sprecher sollten nur dann zugelassen werden, wenn dies für den Arbeitsablauf erforderlich ist.
• Verwenden Sie deterministische Selektoren für deterministische Arbeitsabläufe.
• Weisen Sie Übergaben eine eindeutige Zuständigkeit und eine Endroute zu.
• Teams zwischen unabhängigen Aufgaben neu starten.
• Verfolgung von Drehungen und Erkennung wiederholter Aktionen bei unverändertem Zustand.

Was man nicht tun sollte

Lösen Sie nicht jede Schleife, indem Sie einfach max_messagesden Wert von 25 auf 100 erhöhen. Das ändert die Kosten eines Fehlers, nicht die Logik. Fügen Sie keine längere Systemabfrage hinzu, bevor Sie geprüft haben, ob die Abbruchbedingung tatsächlich im Team implementiert ist. Lassen Sie nicht zwei Agenten die „Abschlussprüfung“ gemeinsam durchführen. Geben Sie keine mehrdeutigen Tool-Strings zurück, wenn der nächste Modellaufruf entscheiden muss, ob ein Wiederholungsversuch unternommen wird. Und gehen Sie nicht davon aus, dass ein Lauf, der schließlich abbricht, fehlerfrei ist: Ein Workflow, der immer seine Sicherheitsgrenze erreicht, ist dennoch fehlerhaft.

Wann sollte man migrieren, anstatt ständig Patches zu installieren?

Wenn Sie eine bestehende AutoGen-Anwendung warten, sind diese Korrekturen angemessen und die aktuelle Dokumentation bleibt verfügbar. Bei einem neuen System oder einer grundlegenden Überarbeitung der Orchestrierung ändert sich die Entscheidung jedoch aufgrund des Wartungsmodus. Microsoft verweist neue Benutzer nun auf das Microsoft Agent Framework. Die zugehörige Migrationsdokumentation beschreibt den Wechsel von AutoGens ereignisgesteuertem Kern und den übergeordneten Teams hin zu typisierten, graphbasierten Workflows. Das bedeutet nicht, dass eine AutoGen-Schleife sofort migriert werden muss, aber Sie sollten den Aufwand für tiefergehende AutoGen-spezifische Orchestrierungsarbeiten gegen den Nutzen des Wechsels zum unterstützten Nachfolger abwägen.

Der kürzeste zuverlässige Weg zur Fehlersuche ist daher: den Ablauf begrenzen, den sich wiederholenden Übergang identifizieren, den Fortschritt beobachtbar machen und schließlich den Ausstieg deterministisch gestalten. Sobald diese vier Schritte abgeschlossen sind, werden die meisten „endlosen“ AutoGen-Schleifen zu gewöhnlichen Workflow-Fehlern, die Sie reproduzieren und beheben können.

Offizielle Referenzen

• Microsoft AutoGen-Repository – aktueller Wartungsmodus-Hinweis.
• AutoGen-Releases – Informationen zu stabilen Python-Versionen.
• Anleitung zur Beendigung von AutoGen AgentChat .
• AutoGen SelectorGroupChat-Anleitung .
• AutoGen AssistantAgent API-Referenz .
• Leitfaden für AutoGen-Teams .
• Migrationsleitfaden von Microsoft AutoGen zu Agent-Framework – aktualisiert am 25. August 2026.