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.
SelectorGroupChatUtiliza um modelo para escolher o próximo participante a partir do contexto da conversa compartilhada. A documentação estável observa que os nomes e descrições dos participantes são importantes, pois são usados na seleção do participante. Por padrão, o mesmo participante não é selecionado consecutivamente, a menos que seja o único agente disponível, embora a opção ` --selector` allow_repeated_speaker=Truealtere esse comportamento. O AutoGen também oferece opções selector_funcpara quando você precisar de um controle mais determinístico. Consulte a documentaçãocandidate_func oficial do SelectorGroupChat .
Se o mesmo participante continuar sendo selecionado, verifique estes itens em ordem:
allow_repeated_speakerdesativado, a menos que as repetições consecutivas sejam realmente necessárias.selector_funcquando o fluxo de trabalho for, na verdade, uma máquina de estados disfarçada de conversa.A distinção fundamental é simples: utilize a seleção de locutor baseada em LLM quando o próximo locutor realmente exigir julgamento semântico. Utilize o roteamento determinístico quando o próximo locutor for ditado pelo estado do fluxo de trabalho.
Na versão atual do AgentChat, AssistantAgentexiste um max_tool_iterationsparâmetro. A documentação da API estável indica que o valor padrão é 1; ao ser aumentado, o agente pode fazer chamadas sequenciais adicionais às ferramentas até que o modelo retorne uma resposta de texto ou o máximo seja atingido. Isso significa que a execução de um único agente é limitada por essa configuração, mas o mesmo agente ainda pode ser selecionado novamente por uma equipe e repetir o mesmo padrão de falha de ferramenta em outras rodadas. Consulte a referência oficial da API do AssistantAgent .
agent = AssistantAgent(
name="worker",
model_client=model_client,
tools=[lookup_tool],
max_tool_iterations=3,
)
Se você se depara com a mesma ferramenta e os mesmos argumentos repetidamente, reduzir o limite de iterações apenas atenua o problema. A solução definitiva geralmente está no contrato da ferramenta. O modelo precisa de informações suficientes para determinar se a chamada foi bem-sucedida, falhou permanentemente, falhou transitoriamente ou não produziu nenhuma informação nova.
Prefira um resultado conciso e explícito, como:
{
"status": "no_new_data",
"query": "customer_123",
"retryable": false,
"reason": "record already checked",
"next_action": "return_to_planner"
}
Isso é mais útil do que uma string genérica como "Nenhum resultado", porque o modelo consegue perceber que repetir a mesma chamada não representa progresso. Para ferramentas com efeitos colaterais, adicione também idempotência no nível da aplicação, para que uma chamada repetida não possa criar repetidamente o mesmo ticket, pagamento, mensagem ou mutação no banco de dados.
A documentação de referência estável AssistantAgentobserva que várias chamadas de ferramentas podem ser executadas simultaneamente e que chamadas de ferramentas paralelas podem ser desativadas em clientes de modelo compatíveis. Ela também alerta que, se várias transferências forem detectadas, apenas a primeira será executada e recomenda desativar as chamadas de ferramentas paralelas para evitar essa situação. Se o seu fluxo de trabalho pressupõe transições de estado estritas, de uma ação por vez, as chamadas paralelas podem dificultar a compreensão do estado resultante.
Um ciclo de transferência geralmente se parece com isto: o Agente A decide que o Agente B é mais adequado, o Agente B vê um contexto incompleto e devolve a tarefa, e ambas as escolhas permanecem localmente razoáveis indefinidamente. O problema não é que nenhum dos modelos esteja "errado". A política de transferência carece de propriedade e de um estado final.
Corrija isso atribuindo a cada transferência uma condição específica e uma regra para o que acontece quando o destino não consegue progredir. Para fluxos de trabalho interativos com o usuário, o sistema HandoffTermination(target="user")foi projetado para interromper a equipe quando o controle deve retornar ao aplicativo ou à pessoa. A documentação do AutoGen sobre interação humana também explica que os fluxos de trabalho do Swarm precisam de um comportamento de retomada deliberado após uma transferência de responsabilidade para o usuário. Consulte a documentação oficial sobre interação humana .
Um bom contrato de transição inclui:
GraphFlowSuporta ciclos deliberados, ramificações condicionais e saídas de loop. A API estável descreve loops como válidos somente quando existe uma condição que eventualmente os encerra, e o construtor valida a estrutura do grafo. Também está marcada como experimental. Um loop estruturalmente válido ainda pode ser executado por tempo excessivo se a condição de saída for logicamente inalcançável, portanto, mantenha uma condição de término independente ou um limite de iterações em torno dele. Consulte a referência da API oficial da equipe AutoGen .
Isso é especialmente importante em projetos com a estrutura “escritor → revisor → escritor”. Se o revisor for instruído a “continuar aprimorando até a perfeição”, a condição de saída pode nunca se concretizar. Substitua a perfeição subjetiva por uma rubrica finita, como seções obrigatórias presentes, verificações de validação aprovadas, ausência de defeitos críticos e número máximo de revisões atingido.
Os agentes e equipes do AgentChat mantêm estado. A documentação estável do AutoGen afirma que a equipe preserva o contexto da conversa entre execuções para que tarefas relacionadas possam continuar, e fornece reset()a opção de limpar o estado da equipe e dos participantes. Esse comportamento é útil para a continuidade, mas pode parecer um loop se uma tarefa não relacionada herdar o contexto antigo, uma delegação incompleta ou suposições anteriores.
await team.reset()
result = await team.run(task=new_unrelated_task)
A API estável do agente também alerta os chamadores para que enviem apenas mensagens novas em cada chamada, em vez de reproduzir manualmente todo o histórico da conversa. Reinserir o histórico completo enquanto o agente mantém o estado pode duplicar o contexto e reforçar comportamentos repetitivos.
Quando um loop for difícil de reproduzir, registre informações suficientes para responder a quatro perguntas para cada interação: quem agiu, por que foi escolhido, qual ação tentou e o que mudou depois. O AutoGen oferece suporte a rastreamento e observabilidade, e o guia de rastreamento estável demonstra o rastreamento de equipes do AgentChat. Consulte a documentação oficial de rastreamento do AutoGen .
No mínimo, registre:
TaskResult.stop_reasonquando a corrida terminar.Um diagnóstico muito eficaz é a detecção de "mesma ação, mesmo estado". Se o mesmo agente invocar a mesma ferramenta com argumentos equivalentes e o hash do estado compartilhado não tiver sido alterado por várias iterações, interrompa a execução e marque-a como um loop sem progresso. Essa verificação reside na lógica do seu aplicativo, em vez de ser um recurso integrado do AutoGen, mas detecta uma classe de falhas que os limites de token ou mensagem só abrangem após o ocorrido.
Para uma aplicação AutoGen AgentChat existente, uma base conservadora é:
max_tool_iterationso número de ferramentas pequeno, a menos que o agente realmente precise de uma sequência de várias etapas.Não resolva todos os loops simplesmente aumentando o valor max_messagesde 25 para 100. Isso altera o custo da falha, não a lógica. Não adicione um prompt de sistema mais longo antes de verificar se a condição de término está realmente configurada na equipe. Não permita que dois agentes sejam responsáveis pela "revisão final". Não retorne strings de ferramentas ambíguas se a próxima chamada do modelo precisar decidir se deve tentar novamente. E não assuma que uma execução que eventualmente para está saudável: um fluxo de trabalho que sempre atinge seu limite de segurança ainda está com defeito.
Se você estiver dando manutenção a um aplicativo AutoGen existente, essas correções são apropriadas e a documentação atual permanece disponível. No entanto, para um novo sistema ou uma grande reformulação da orquestração, o status de modo de manutenção altera a decisão. A Microsoft agora direciona novos usuários para o Microsoft Agent Framework, e sua documentação de migração descreve uma mudança do núcleo orientado a eventos e das equipes de alto nível do AutoGen para fluxos de trabalho tipados e baseados em grafos. Isso não significa que um loop do AutoGen precise ser migrado imediatamente, mas significa que você deve avaliar o custo de um trabalho de orquestração mais aprofundado e específico do AutoGen em comparação com a migração para o sucessor com suporte.
O caminho de depuração mais curto e confiável é, portanto: delimitar a execução, identificar a transição repetitiva, tornar o progresso observável e, em seguida, tornar a saída determinística. Uma vez que esses quatro elementos estejam em vigor, a maioria dos loops "infinitos" do AutoGen se tornam bugs comuns de fluxo de trabalho que você pode reproduzir e corrigir.
Crie uma planilha simples de contagem de estoque para varejo no Excel com colunas práticas, fórmulas de variação, controles de recontagem e um exemplo hipotético realista de uma loja.
Crie uma apresentação de integração de novos funcionários simples que esclareça funções, ferramentas, expectativas, suporte e próximos passos — e saiba quando a apresentação precisa ser alterada.
Compare Ollama and LM Studio for local AI agents in 2026: APIs, tool calling, MCP, headless deployment, model management, coding-agent integrations, and best-fit workflows.
Previna vazamentos de dados de atendimento ao cliente com IA por meio de minimização de dados, controles de acesso determinísticos, defesas contra injeção imediata, filtragem de saída, isolamento de locatários e testes de auditoria.
Corrija o atraso de sincronização labial em vídeos com IA diagnosticando o deslocamento versus a deriva, controlando o ritmo do ElevenLabs, escolhendo o modo de sincronização labial correto do HeyGen e corrigindo apenas os segmentos problemáticos.
Exporte contatos do Salesforce para uma planilha do Excel em branco usando relatórios, CSV e Power Query. Aprenda qual formato escolher, como preservar IDs e zeros à esquerda, remover duplicados e salvar um arquivo .xlsx confiável.
Corrija erros de tempo limite da API em fluxos de trabalho multiagentes, escolhendo o orçamento de tempo limite, a política de repetição, o limite de simultaneidade, o streaming ou a arquitetura de tarefas assíncronas adequados.
Use instruções mais claras, exemplos, instruções personalizadas e uma revisão cuidadosa para reduzir o uso de clichês na linguagem da IA em artigos do ChatGPT, sem tornar a escrita rígida.
Saiba quando é legal remover marcas d'água visíveis de vídeos com IA para uso comercial, quais marcas devem permanecer e como documentar um fluxo de trabalho em conformidade.
Crie um agente prático de processamento de faturas de código aberto com análise de documentos, extração local de LLM, validação, revisão humana, uma API, armazenamento e testes.
