Dlaczego Twój agent AutoGen utknął w nieskończonych pętlach — i jak to naprawić

Przed debugowaniem pętli AutoGen należy zapoznać się z ważną zmianą na platformie. Od września 2026 roku oficjalne repozytorium AutoGen znajduje się w trybie konserwacji: oczekuje się, że będzie ono otrzymywać prace konserwacyjne, a nie nowe funkcje, a Microsoft zaleca korzystanie z Microsoft Agent Framework w przypadku nowych projektów. Oficjalne repozytorium AutoGen nadal wymienia Pythona 0.7.5 jako aktualną stabilną wersję, a Microsoft opublikował zaktualizowany przewodnik migracji z AutoGen do Agent Framework 25 sierpnia 2026 roku. Jeśli jednak AutoGen jest już w środowisku produkcyjnym, poniższe techniki rozwiązywania problemów nadal będą przydatne. Zobacz oficjalne repozytorium AutoGen , oficjalne wydania AutoGen oraz przewodnik migracji AutoGen firmy Microsoft .

Agent AutoGen zazwyczaj wygląda, jakby „utknął w nieskończonej pętli” z jednego z pięciu powodów: przebieg nie ma niezawodnego warunku zakończenia, zasada „następny mówca” ciągle wybiera nieproduktywnego uczestnika, wywołanie narzędzia nie generuje zauważalnego postępu, agenci pracują ręcznie w tę i z powrotem lub aplikacja ciągle powraca do nieaktualnego stanu. Najszybszym rozwiązaniem jest nie przepisywanie każdego komunikatu. Najpierw zidentyfikuj, która pętla faktycznie występuje, następnie dodaj zatrzymanie, a następnie napraw przejście, które nie działa.

Szybka diagnoza: jaki rodzaj pętli widzisz?

1. Dodaj twardy stop przed debugowaniem czegokolwiek innego

AutoGen AgentChat oferuje wbudowane warunki zakończenia, które pozwalają ograniczyć liczbę zespołów. Stabilna dokumentacja zawiera MaxMessageTermination: TextMentionTermination, , TokenUsageTermination, TimeoutTermination, HandoffTermination, SourceMatchTermination, ExternalTermination, StopMessageTermination, TextMessageTermination, FunctionCallTermination, i FunctionalTermination. Zobacz oficjalną dokumentację AutoGen dotyczącą zakończenia .

W większości procesów produkcyjnych należy stosować semantyczny warunek zakończenia i niezależny limit bezpieczeństwa. Ważnym operatorem jest zazwyczaj operator OR, ponieważ chcesz, aby przebieg został zatrzymany, gdy zadanie zakończy się normalnie lub zostanie osiągnięty limit bezpieczeństwa.

from autogen_agentchat.conditions import (
    MaxMessageTermination,
    TextMentionTermination,
)

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

termination = done | safety_cap

Częstym błędem jest poleganie wyłącznie na „powiedz TERMINATE po zakończeniu”. To pozostawia poprawność działaniu modelu. Innym błędem jest łączenie warunków z sytuacją, &gdy tak naprawdę masz na myśli „zatrzymaj po obu stronach”. AutoGen obsługuje zarówno złożenie AND, jak i OR, więc semantyka powinna być dobierana rozważnie.

Co to naprawia

• Zespół, który nigdy nie osiąga oczekiwanego efektu końcowego.
• Selektor, który ciągle znajduje inny głośnik, mimo że pożyteczna praca została przerwana.
• Łańcuch przekazywania nie mający naturalnego końca.
• Nieoczekiwane zachowanie modelu lub narzędzia, które w innym przypadku wymagałoby nieograniczonej liczby obrotów.

Twardy limit to wyłącznik automatyczny, a nie dowód na poprawność przepływu pracy. Jeśli przebieg zawsze zatrzymuje się po osiągnięciu limitu, nadal masz problem logiczny do rozwiązania.

2. Uczyń uzupełnianie wykrywalnym przez maszynę, a nie tylko konwersacyjnym

Najsilniejszy sygnał zakończenia to taki, który aplikacja może rozpoznać bez interpretowania prozy. Jeśli przepływ pracy ma wyraźne zdarzenie powodzenia, użyj najbliższego, pasującego warunku zakończenia. Na przykład, konkretne przekazanie można wykryć za pomocą HandoffTermination, zakończenie działania konkretnego narzędzia można wykryć za pomocą FunctionCallTermination, a niestandardową logikę można wyrazić za pomocą FunctionalTermination.

Jeśli używasz TextMentionTermination("TERMINATE"), jasno określ odpowiedzialność: który agent ma prawo zadeklarować ukończenie i pod jakim zweryfikowanym warunkiem? Unikaj dawania każdemu uczestnikowi niejasnych instrukcji, takich jak „kontynuuj, aż do spełnienia”. Tego rodzaju instrukcje mogą prowadzić do niekończącej się krytyki i przepisywania, ponieważ „spełnienie” nie ma obserwowalnej granicy.

Przydatny kontrakt na ukończenie projektu jest konkretny: „Recenzent emituje komunikat TERMINATE dopiero wtedy, gdy wersja robocza zawiera wszystkie trzy wymagane sekcje i nie ma już żadnej otwartej blokady”. Jeszcze lepiej, jeśli to praktyczne, zobowiąż recenzenta do stworzenia ustrukturyzowanego stanu, który aplikacja może sprawdzić.

3. Napraw routing SelectorGroupChat przed przepisaniem wszystkich monitów agenta

SelectorGroupChatWykorzystuje model do wyboru kolejnego mówcy z kontekstu współdzielonej konwersacji. W stabilnej dokumentacji zaznaczono, że imiona i nazwiska uczestników oraz ich opisy mają znaczenie, ponieważ są wykorzystywane do wyboru mówcy. Domyślnie ten sam mówca nie jest wybierany kolejno, chyba że jest jedynym dostępnym agentem, chociaż allow_repeated_speaker=Truezmienia to zachowanie. AutoGen zapewnia również dostęp selector_funcdo candidate_funcbardziej deterministycznej kontroli, gdy jest to potrzebne. Zapoznaj się z oficjalną dokumentacją SelectorGroupChat .

Jeśli ten sam uczestnik jest ciągle wybierany, zaznacz kolejno poniższe pola:

• Opisy agentów: każdy opis powinien określać, co agent robi i kiedy powinien zostać wybrany. Nakładające się na siebie opisy powodują niestabilność routingu.
• Monit selektora: zadbaj o to, aby reguły routingu były wystarczająco krótkie, aby model mógł być niezawodnie stosowany. Dokumentacja AutoGen wyraźnie zaleca rozważenie użycia niestandardowego selektora, gdy monit zaczyna gromadzić wiele warunków.
• Powtarzające się ustawienia głośników: należy allow_repeated_speakerwyłączyć, chyba że kolejne obroty są rzeczywiście konieczne.
• Ograniczenie kandydatów: jeśli po osiągnięciu określonego stanu ważne są tylko dwaj agenci, ogranicz zbiór kandydatów, zamiast prosić model o dokonanie wyboru spośród każdego uczestnika.
• Przejścia deterministyczne: należy ich używać selector_func, gdy przepływ pracy jest w rzeczywistości maszyną stanów przebraną za konwersację.

Kluczowa różnica jest prosta: stosuj selekcję mówców opartą na LLM, gdy kolejny mówca rzeczywiście wymaga oceny semantycznej. Stosuj routing deterministyczny, gdy kolejny mówca jest dyktowany przez stan przepływu pracy.

4. Zatrzymaj wielokrotne wywoływanie narzędzi, uwidaczniając postęp

W obecnym AgentChat AssistantAgentma max_tool_iterationsparametr. Dokumentacja stabilnego API podaje, że domyślna wartość to 1; po jej zwiększeniu agent może wykonywać dodatkowe sekwencyjne wywołania narzędzi, aż model zwróci odpowiedź tekstową lub zostanie osiągnięty limit. Oznacza to, że pojedyncze uruchomienie agenta jest ograniczone tym ustawieniem, ale ten sam agent może zostać ponownie wybrany przez zespół i powtórzyć ten sam nieudany schemat użycia narzędzia w kolejnych turach. Zobacz oficjalną dokumentację API AssistantAgent .

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

Jeśli widzisz to samo narzędzie i argumenty wielokrotnie, zmniejszenie limitu iteracji ograniczy jedynie szkody. Podstawowa poprawka znajduje się zazwyczaj w kontrakcie narzędzia. Model potrzebuje wystarczającej ilości informacji, aby stwierdzić, czy wywołanie zakończyło się powodzeniem, trwałym niepowodzeniem, przejściowym niepowodzeniem, czy też nie wygenerowało żadnych nowych informacji.

Preferuj zwarty i wyraźny wynik, taki jak:

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

Jest to bardziej przydatne niż ogólny ciąg znaków, taki jak „Brak wyniku”, ponieważ model widzi, że powtarzanie tego samego wywołania nie oznacza postępu. W przypadku narzędzi powodujących efekty uboczne należy również dodać idempotentność na poziomie aplikacji, aby powtarzane wywołanie nie mogło wielokrotnie tworzyć tego samego biletu, płatności, wiadomości ani mutacji bazy danych.

Sprawdź również równoległe wywołania narzędzi

W stabilnej AssistantAgentdokumentacji zaznaczono, że wiele wywołań narzędzi może być wykonywanych jednocześnie, a równoległe wywołania narzędzi można wyłączyć w obsługiwanych modelach klientów. Ostrzega również, że w przypadku wykrycia wielu przełączeń, wykonywane jest tylko pierwsze, i zaleca wyłączenie równoległych wywołań narzędzi, aby uniknąć takiej sytuacji. Jeśli w przepływie pracy zakłada się przejścia między stanami w trybie jednej akcji na raz, równoległe wywołania mogą utrudnić interpretację stanu wynikowego.

5. Przerwij przekazanie ping-ponga w zespołach w stylu Swarm

Pętla przekazania zazwyczaj wygląda tak: Agent A decyduje, że Agent B jest bardziej odpowiedni, Agent B widzi niepełny kontekst i odsyła zadanie, a oba wybory pozostają lokalnie uzasadnione na zawsze. Problem nie polega na tym, że którykolwiek z modeli jest „błędny”. Polityka przekazania nie ma poczucia własności ani stanu końcowego.

Rozwiązaniem tego problemu jest nadanie każdemu przekazaniu wąskiego warunku i reguły określającej, co się stanie, gdy cel nie będzie mógł zrobić postępów. W przypadku przepływów pracy z interakcją z użytkownikiem, HandoffTermination(target="user")ma to na celu zatrzymanie zespołu w momencie, gdy kontrola powinna wrócić do aplikacji lub osoby. Dokumentacja AutoGen dotycząca interakcji z użytkownikiem wyjaśnia również, że przepływy pracy Swarm wymagają celowego wznowienia po przekazaniu przez użytkownika. Zobacz oficjalną dokumentację dotyczącą interakcji z użytkownikiem .

Dobry kontrakt przekazania obejmuje:

• dokładne możliwości, jakie posiada cel;
• dowody uzasadniające przekazanie;
• co powinien zwrócić cel w przypadku powodzenia;
• co powinien zrobić cel, jeśli brakuje wymaganych informacji;
• zakaz odsyłania zadania w niezmienionej formie.

6. Traktuj cykle GraphFlow jak prawdziwe pętle wymagające jawnych wyjść

GraphFlowObsługuje celowe cykle, rozgałęzienia warunkowe i wyjścia z pętli. Stabilne API opisuje pętle jako poprawne tylko wtedy, gdy istnieje warunek, który ostatecznie je kończy, a konstruktor weryfikuje strukturę grafu. Jest również oznaczone jako eksperymentalne. Strukturalnie poprawna pętla może nadal działać zbyt długo, jeśli warunek wyjścia jest logicznie nieosiągalny, dlatego należy zachować niezależny warunek zakończenia lub obrócić go w celu ograniczenia. Zobacz oficjalną dokumentację API zespołów AutoGen .

Ma to szczególne znaczenie w projektach typu „autor → recenzent → autor”. Jeśli recenzent otrzyma polecenie „ciągłego doskonalenia aż do perfekcji”, predykat wyjścia może nigdy nie zostać spełniony. Zastąp subiektywną doskonałość skończoną rubryką, taką jak obecność wymaganych sekcji, pozytywne zatwierdzenie walidacji, brak krytycznych błędów i osiągnięcie maksymalnej liczby poprawek.

7. Zresetuj stan, gdy następne zadanie nie jest już powiązane

Agenci i zespoły w AgentChat korzystają z funkcji stanowych. Stabilna dokumentacja AutoGen mówi, że zespół zachowuje kontekst konwersacji między uruchomieniami, aby powiązane zadania mogły być kontynuowane, a także zapewnia reset()czyste dane zespołu i uczestników. To zachowanie jest przydatne w przypadku kontynuacji, ale może wyglądać jak pętla, jeśli niepowiązane zadanie dziedziczy stary kontekst, niedokończone delegowanie lub wcześniejsze założenia.

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

Stabilny interfejs API agenta ostrzega również wywołujących, aby przekazywali tylko nowe wiadomości przy każdym wywołaniu, zamiast ręcznie odtwarzać całą historię konwersacji. Ponowne wstrzyknięcie pełnej historii, podczas gdy agent również utrzymuje stan, może duplikować kontekst i wzmacniać powtarzające się zachowania.

8. Rejestruj przejście, a nie tylko ostateczny tekst

Gdy pętla jest trudna do odtworzenia, zbierz wystarczająco dużo informacji, aby odpowiedzieć na cztery pytania dla każdej tury: kto wykonał działanie, dlaczego został wybrany, jaką akcję podjął i co się zmieniło później. AutoGen zapewnia wsparcie śledzenia i obserwowalności, a stabilny przewodnik śledzenia demonstruje śledzenie zespołów AgentChat. Zobacz oficjalną dokumentację śledzenia AutoGen .

Co najmniej zaloguj się:

• ID biegu i numer zakrętu;
• źródło wiadomości i typ wiadomości;
• wybrani prelegenci i dostępni kandydaci;
• nazwa narzędzia plus hash lub znormalizowana forma argumentów;
• status narzędzia i czy stan uległ zmianie;
• źródło i cel przekazania;
• wynik warunku zakończenia;
• TaskResult.stop_reasonkiedy bieg się kończy.

Bardzo skuteczną diagnostyką jest wykrywanie „tej samej akcji, tego samego stanu”. Jeśli ten sam agent wywołuje to samo narzędzie z równoważnymi argumentami, a współdzielony skrót stanu nie zmienił się przez kilka tur, należy zatrzymać działanie i oznaczyć je jako pętlę bez postępu. To sprawdzenie jest częścią logiki aplikacji, a nie wbudowaną funkcją AutoGen, ale wychwytuje klasę błędów, które limity tokenów lub komunikatów uwzględniają dopiero po fakcie.

Praktyczna, bezpieczna linia bazowa

W przypadku istniejącej aplikacji AutoGen AgentChat konserwatywnym punktem odniesienia jest:

• Zawsze konfiguruj twardą wiadomość, obrót, limit czasu lub limit tokena.
• Połącz ten pułap z sensownym warunkiem ukończenia za pomocą operatora OR, gdy którykolwiek z nich powinien zatrzymać przebieg.
• Stosuj max_tool_iterationsmałe rozwiązania, chyba że agent faktycznie potrzebuje wieloetapowej sekwencji narzędzi.
• Zwraca ustrukturyzowane wyniki narzędzia, które rozróżniają sukces, brak postępu, błąd powtarzalny i błąd trwały.
• Nie zezwalaj na powtarzanie rozmówców, chyba że przepływ pracy tego wymaga.
• Użyj selektorów deterministycznych dla deterministycznych przepływów pracy.
• Nadaj przekazaniom jawną własność i trasę końcową.
• Resetuj zespoły pomiędzy niezwiązanymi ze sobą zadaniami.
• Śledzenie obrotów i wykrywanie powtarzających się czynności przy niezmienionym stanie.

Czego nie robić

Nie rozwiązuj każdej pętli, po prostu zwiększając ją max_messagesz 25 do 100. To zmienia koszt awarii, a nie logikę. Nie dodawaj dłuższego monitu systemowego przed sprawdzeniem, czy warunek zakończenia jest rzeczywiście wbudowany w zespół. Nie pozwól, aby dwaj agenci posiadali jednocześnie „ostateczną kontrolę”. Nie zwracaj niejednoznacznych ciągów narzędzi, jeśli kolejne wywołanie modelu musi zdecydować o ponownych próbach. I nie zakładaj, że przebieg, który w końcu się zatrzyma, jest prawidłowy: przepływ pracy, który zawsze osiąga swój limit bezpieczeństwa, nadal działa nieprawidłowo.

Kiedy migrować zamiast ciągle stosować poprawki

Jeśli utrzymujesz istniejącą aplikację AutoGen, te poprawki są odpowiednie, a aktualna dokumentacja pozostaje dostępna. Jednak w przypadku nowego systemu lub gruntownej przeróbki orkiestracji, status trybu konserwacji zmienia decyzję. Firma Microsoft kieruje teraz nowych użytkowników do platformy Microsoft Agent Framework, a dokumentacja dotycząca migracji opisuje przejście od rdzenia AutoGen sterowanego zdarzeniami i zespołów wysokiego szczebla do typowanych, opartych na grafach przepływów pracy. Nie oznacza to, że pętla AutoGen musi zostać natychmiast zmigrowana, ale oznacza to, że należy rozważyć koszt bardziej zaawansowanej orkiestracji specyficznej dla AutoGen w kontekście przejścia na wspieraną następczynię.

Najkrótsza, niezawodna ścieżka debugowania to zatem: ograniczenie przebiegu, identyfikacja powtarzających się przejść, uczynienie postępu obserwowalnym, a następnie uczynienie wyjścia deterministycznym. Po wdrożeniu tych czterech elementów, większość „nieskończonych” pętli AutoGen staje się zwykłymi błędami w przepływie pracy, które można odtworzyć i naprawić.

Oficjalne referencje

• Repozytorium Microsoft AutoGen — bieżące powiadomienie w trybie konserwacji.
• Wydania AutoGen — informacje o stabilnych wydaniach Pythona.
• Instrukcja zakończenia działania AutoGen AgentChat .
• Przewodnik po AutoGen SelectorGroupChat .
• Dokumentacja API AutoGen AssistantAgent .
• Przewodnik po zespołach AutoGen .
• Przewodnik po migracji z Microsoft AutoGen do Agent-Framework — aktualizacja z 25 sierpnia 2026 r.