There is an important platform change to know before debugging an AutoGen loop. As of September 2026, the official AutoGen repository is in maintenance mode: it is expected to receive maintenance work rather than new features, and Microsoft recommends Microsoft Agent Framework for new projects. The official AutoGen repository still lists Python 0.7.5 as the current stable line, while Microsoft published an updated AutoGen-to-Agent-Framework migration guide on August 25, 2026. If you already have AutoGen in production, though, the troubleshooting techniques below remain directly useful. See the official AutoGen repository, the official AutoGen releases, and Microsoft's AutoGen migration guide.
An AutoGen agent usually looks “stuck in an infinite loop” for one of five reasons: the run has no reliable termination condition, the next-speaker policy keeps choosing an unproductive participant, a tool call does not create observable progress, agents hand work back and forth, or the application keeps resuming stale state. The fastest fix is not to rewrite every prompt. First identify which loop you actually have, then add a hard stop, then repair the transition that is failing.
| Symptom | Likely cause | First thing to check |
|---|---|---|
| The same two agents alternate indefinitely | Routing or handoff ping-pong | Speaker selection, handoff targets, and a maximum-message or maximum-turn limit |
| One agent repeatedly calls the same tool with nearly identical arguments | Tool result does not prove progress or failure | max_tool_iterations, tool return schema, and retry logic |
| The team keeps talking after the task is visibly complete | Completion is only implied in the prompt | Explicit termination condition and deterministic completion signal |
| A selector repeatedly chooses the wrong specialist | Ambiguous agent descriptions or selector prompt | Participant descriptions, candidate set, and allow_repeated_speaker |
| A new task seems to inherit the previous task's behavior | State was intentionally preserved | Whether the team or agent should be reset before the new task |
| A graph workflow cycles forever through review/rewrite | Exit condition never becomes true | Cycle exit predicate plus an independent safety termination |
AutoGen AgentChat provides built-in termination conditions specifically to keep teams bounded. The stable documentation includes MaxMessageTermination, TextMentionTermination, TokenUsageTermination, TimeoutTermination, HandoffTermination, SourceMatchTermination, ExternalTermination, StopMessageTermination, TextMessageTermination, FunctionCallTermination, and FunctionalTermination. See the official AutoGen termination documentation.
For most production workflows, use a semantic completion condition and an independent safety ceiling. The important operator is usually OR, because you want the run to stop when either the task finishes normally or the safety limit is reached.
from autogen_agentchat.conditions import (
MaxMessageTermination,
TextMentionTermination,
)
done = TextMentionTermination("TERMINATE")
safety_cap = MaxMessageTermination(max_messages=25)
termination = done | safety_cap
A common mistake is relying only on “say TERMINATE when done.” That leaves correctness to model behavior. Another mistake is combining conditions with & when you actually mean “stop on either.” AutoGen supports both AND and OR composition, so choose the semantics deliberately.
A hard cap is a circuit breaker, not proof that the workflow is correct. If the run always stops because it hits the cap, you still have a logic problem to fix.
The strongest termination signal is one your application can recognize without interpreting prose. If the workflow has a clear success event, use the closest matching termination condition. For example, a specific handoff can be detected with HandoffTermination, a particular tool completion can be detected with FunctionCallTermination, and custom logic can be expressed with FunctionalTermination.
If you use TextMentionTermination("TERMINATE"), make the responsibility explicit: which agent is allowed to declare completion, and under what verified condition? Avoid giving every participant vague instructions such as “continue until satisfied.” That kind of instruction can produce endless critique-and-rewrite behavior because “satisfied” has no observable boundary.
A useful completion contract is concrete: “The reviewer emits TERMINATE only after the draft contains all three required sections and no open blocker remains.” Better still, when practical, make the reviewer produce structured state that the application can check.
SelectorGroupChatИспользуется модель для выбора следующего говорящего из общего контекста разговора. В стабильной документации отмечается, что имена и описания участников имеют значение, поскольку они используются при выборе говорящего. По умолчанию один и тот же говорящий не выбирается последовательно, если только он не является единственным доступным агентом, хотя allow_repeated_speaker=Trueэто поведение изменяется. AutoGen также предоставляет возможности selector_func, candidate_funcкогда требуется более детерминированный контроль. Ознакомьтесь с официальной документацией SelectorGroupChat .
Если одного и того же участника выбирают постоянно, проверьте следующие пункты по порядку:
allow_repeated_speakerотключайте, если только не требуется действительно последовательное включение.selector_func, когда рабочий процесс на самом деле представляет собой конечный автомат, замаскированный под диалог.Ключевое различие простое: используйте выбор говорящего на основе LLM, когда для выбора следующего говорящего действительно требуется семантическая оценка. Используйте детерминированную маршрутизацию, когда выбор следующего говорящего определяется состоянием рабочего процесса.
В текущей версии AgentChat AssistantAgentесть max_tool_iterationsпараметр. В документации стабильного API указано, что значение по умолчанию равно 1; при увеличении этого значения агент может совершать дополнительные последовательные вызовы инструментов, пока модель не вернет текстовый ответ или не будет достигнуто максимальное значение. Это означает, что один запуск агента ограничен этим параметром, но тот же агент может быть снова выбран командой и повторять ту же схему неудачных вызовов инструментов в течение нескольких ходов. См. официальную справочную информацию по API AssistantAgent .
agent = AssistantAgent(
name="worker",
model_client=model_client,
tools=[lookup_tool],
max_tool_iterations=3,
)
Если вы постоянно используете один и тот же инструмент и аргументы, уменьшение лимита итераций лишь локализует проблему. Коренное решение обычно кроется в контракте инструмента. Модель должна обладать достаточной информацией, чтобы определить, был ли вызов успешным, завершился ли с ошибкой окончательно, произошел ли временный сбой или не дал никакой новой информации.
Предпочтительнее получить лаконичный и понятный результат, например:
{
"status": "no_new_data",
"query": "customer_123",
"retryable": false,
"reason": "record already checked",
"next_action": "return_to_planner"
}
Это полезнее, чем общая строка типа «Нет результата», потому что модель может видеть, что повторение одного и того же вызова не является прогрессом. Для инструментов, имеющих побочные эффекты, также следует добавить идемпотентность на уровне приложения, чтобы повторный вызов не мог многократно создавать один и тот же тикет, платеж, сообщение или изменение базы данных.
В стабильной AssistantAgentверсии справочника отмечается, что несколько вызовов инструментов могут выполняться одновременно, и что параллельные вызовы инструментов можно отключить в поддерживаемых клиентских приложениях для работы с моделями. Также предупреждается, что если обнаружено несколько передач данных, выполняется только первая, и рекомендуется отключить параллельные вызовы инструментов, чтобы избежать такой ситуации. Если ваш рабочий процесс предполагает строгие переходы состояний по одному действию за раз, параллельные вызовы могут затруднить анализ результирующего состояния.
Цикл передачи задачи обычно выглядит так: Агент А решает, что Агент Б лучше подходит для этой задачи, Агент Б видит неполный контекст и отправляет задачу обратно, и оба варианта остаются локально обоснованными навсегда. Проблема не в том, что какая-либо из моделей «неправильна». В политике передачи задачи отсутствует право собственности и конечное состояние.
Исправьте это, задав для каждой передачи управления узкое условие и правило, определяющее, что происходит, когда целевой объект не может продолжить работу. Для рабочих процессов с взаимодействием с пользователем HandoffTermination(target="user")это предназначено для остановки команды, когда управление должно вернуться к приложению или человеку. В документации AutoGen по работе с участием человека также объясняется, что рабочие процессы Swarm требуют целенаправленного возобновления работы после передачи управления пользователю. См. официальную документацию по работе с участием человека .
Хороший договор о передаче дел включает в себя:
GraphFlowПоддерживаются преднамеренные циклы, условное ветвление и выходы из циклов. В стабильном API циклы считаются допустимыми только при наличии условия, которое в конечном итоге приводит к выходу из цикла, и построитель проверяет структуру графа. Он также помечен как экспериментальный. Структурно допустимый цикл может продолжаться слишком долго, если условие выхода логически недостижимо, поэтому следует предусмотреть независимое условие завершения или ограничение количества ходов. См. официальный справочник API для команд AutoGen .
Это особенно важно в схемах типа «автор → рецензент → автор». Если рецензенту дается указание «продолжать совершенствоваться до совершенства», условие завершения может никогда не стать истинным. Замените субъективное совершенство конечной рубрикой, такой как наличие необходимых разделов, прохождение проверок валидации, отсутствие критических дефектов и достижение максимального количества правок.
Агенты и команды AgentChat сохраняют состояние. В стабильной документации AutoGen говорится, что команда сохраняет контекст разговора между запусками, чтобы связанные задачи могли продолжаться, и предоставляется reset()возможность очистки состояния команды и участников. Такое поведение полезно для обеспечения непрерывности, но может выглядеть как цикл, если несвязанная задача наследует старый контекст, незавершенное делегирование или предыдущие предположения.
await team.reset()
result = await team.run(task=new_unrelated_task)
В стабильной версии API агента также содержится предупреждение о необходимости передавать только новые сообщения при каждом звонке, а не воспроизводить всю историю разговора вручную. Повторное внедрение полной истории при одновременном сохранении состояния агентом может привести к дублированию контекста и усилению повторяющегося поведения.
Если цикл сложно воспроизвести, запишите достаточно информации, чтобы ответить на четыре вопроса для каждого хода: кто совершил действие, почему он был выбран, какое действие он попытался выполнить и что изменилось после этого. AutoGen обеспечивает поддержку трассировки и мониторинга, а в стабильном руководстве по трассировке демонстрируется трассировка команд AgentChat. См. официальную документацию по трассировке AutoGen .
Как минимум, лог:
TaskResult.stop_reasonкогда забег закончится.Очень эффективным методом диагностики является обнаружение «одно и то же действие, одно и то же состояние». Если один и тот же агент запускает один и тот же инструмент с эквивалентными аргументами, и общий хэш состояния не менялся в течение нескольких циклов, остановите выполнение и пометьте его как цикл без прогресса. Эта проверка находится в логике вашего приложения, а не является встроенной функцией AutoGen, но она выявляет класс ошибок, которые ограничения по токенам или сообщениям обнаруживают только постфактум.
Для существующего приложения AutoGen AgentChat консервативный базовый вариант выглядит следующим образом:
max_tool_iterationsинструменты небольшого размера, если только агенту действительно не требуется многоэтапная последовательность действий.Не следует решать каждую проблему, просто увеличивая значение max_messagesс 25 до 100. Это меняет стоимость ошибки, а не логику. Не добавляйте более длинный системный запрос перед проверкой того, действительно ли условие завершения задано командой. Не позволяйте двум агентам одновременно отвечать за «окончательный обзор». Не возвращайте неоднозначные строки инструментов, если следующий вызов модели должен решить, следует ли повторять попытку. И не следует предполагать, что выполнение, которое в конечном итоге останавливается, является корректным: рабочий процесс, который всегда достигает своего предела безопасности, все еще неисправен.
Если вы поддерживаете существующее приложение AutoGen, эти исправления уместны, и текущая документация остается доступной. Однако для новой системы или масштабной переработки системы оркестрации статус режима поддержки меняет решение. Microsoft теперь рекомендует новым пользователям использовать Microsoft Agent Framework, и в документации по миграции описывается переход от событийно-ориентированного ядра AutoGen и высокоуровневых команд к типизированным рабочим процессам на основе графов. Это не означает, что цикл AutoGen необходимо немедленно перенести, но это означает, что следует взвесить затраты на более глубокую работу по оркестрации, специфичную для AutoGen, по сравнению с переходом на поддерживаемую версию.
Таким образом, кратчайший и надежный путь отладки состоит в следующем: ограничить выполнение программы, определить повторяющийся переход, сделать ход выполнения наблюдаемым, а затем сделать выход детерминированным. Как только эти четыре элемента будут на месте, большинство «бесконечных» циклов AutoGen превратятся в обычные ошибки рабочего процесса, которые можно воспроизвести и исправить.
Создайте локальный рабочий процесс Ollama, который будет генерировать структурированные SEO-заголовки и метаописания в пакетном режиме, проверять результаты и помечать их для проверки человеком.
Use this free modern real estate listing presentation PowerPoint blueprint to organize pricing, marketing, property prep, agent value, and seller next steps.
Создайте в Excel шаблон сметы строительных работ, который можно распечатать, с четким указанием трудозатрат, материалов, формул, наценки, исключений и готовыми к печати итоговыми суммами для клиента.
Создавайте более эффективные видеоподсказки для Luma Dream Machine с помощью практичной формулы кинематографического освещения, многоразовых рецептов, примеров и быстрого контрольного списка для устранения неполадок.
Создайте минималистичную презентацию для инвесторов технологического стартапа в PowerPoint, используя правильный порядок слайдов, четкие правила дизайна, показатели эффективности и готовое к использованию приложение.
Предотвратите преобразование кодов, идентификаторов и дробей в даты в Excel. Используйте текстовый формат, апострофы, элементы управления импортом и текущие параметры Microsoft 365.
Ускорьте рендеринг ComfyUI SDXL за счет сокращения объема работы по сэмплированию, контроля разрешения и размера пакета, упрощения узлов, использования кэширования, а также безопасной настройки видеопамяти и механизма внимания.
Создайте в Excel практичную систему учета доходов и расходов от сдачи недвижимости в аренду, включающую четкие категории, формулы, ежемесячные сводки и рекомендации по ведению налоговой отчетности.
Создайте частную локальную базу знаний по искусственному интеллекту с помощью Ollama, AnythingLLM, локальных эмбеддингов и RAG. Изучите четырехэтапную настройку, проверки конфиденциальности, тестирование и резервное копирование.
Исправьте ошибки контекстного окна при анализе длинных документов, обрезав входные данные, разделив файлы, используя поиск и убедившись, что окончательный ответ охватывает исходный текст.
