¿Por qué tu agente AutoGen se queda atascado en bucles infinitos y cómo solucionarlo?

Hay un cambio importante en la plataforma que debe conocer antes de depurar un bucle de AutoGen. A partir de septiembre de 2026, el repositorio oficial de AutoGen está en modo de mantenimiento: se espera que reciba tareas de mantenimiento en lugar de nuevas funciones, y Microsoft recomienda Microsoft Agent Framework para nuevos proyectos. El repositorio oficial de AutoGen todavía indica Python 0.7.5 como la versión estable actual, mientras que Microsoft publicó una guía de migración actualizada de AutoGen a Agent Framework el 25 de agosto de 2026. Sin embargo, si ya tiene AutoGen en producción, las técnicas de solución de problemas que se describen a continuación siguen siendo directamente útiles. Consulte el repositorio oficial de AutoGen , las versiones oficiales de AutoGen y la guía de migración de AutoGen de Microsoft .

Un agente de AutoGen suele parecer atrapado en un bucle infinito por una de estas cinco razones: la ejecución no tiene una condición de finalización fiable, la política del siguiente orador sigue eligiendo a un participante improductivo, una llamada a una herramienta no genera un progreso observable, los agentes realizan tareas de forma errática o la aplicación sigue retomando un estado obsoleto. La solución más rápida no consiste en reescribir todas las indicaciones. Primero, identifique el bucle que tiene, luego añada una parada forzada y, finalmente, corrija la transición que está fallando.

Diagnóstico rápido: ¿qué tipo de bucle está observando?

1. Agrega un punto de parada forzoso antes de depurar cualquier otra cosa.

AutoGen AgentChat proporciona condiciones de terminación integradas específicamente para mantener a los equipos acotados. La documentación estable incluye MaxMessageTermination, TextMentionTermination, TokenUsageTermination, TimeoutTermination, HandoffTermination, SourceMatchTermination, ExternalTermination, StopMessageTermination, TextMessageTermination, FunctionCallTermination, y FunctionalTermination. Consulte la documentación oficial de terminación de AutoGen .

Para la mayoría de los flujos de trabajo de producción, utilice una condición de finalización semántica y un límite de seguridad independiente. El operador clave suele ser OR, ya que se desea que la ejecución se detenga cuando la tarea finalice correctamente o se alcance el límite de seguridad.

from autogen_agentchat.conditions import (
    MaxMessageTermination,
    TextMentionTermination,
)

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

termination = done | safety_cap

Un error común es confiar únicamente en «decir TERMINAR cuando termine». Esto deja la corrección en manos del modelo de comportamiento. Otro error es combinar condiciones &cuando en realidad se quiere decir «detenerse en cualquiera de los dos casos». AutoGen admite la composición AND y OR, así que elija la semántica con cuidado.

Lo que esto soluciona

• Un equipo que nunca produce la frase de finalización esperada.
• Un selector que sigue encontrando otro altavoz aunque el trabajo útil se haya detenido.
• Una cadena de traspasos que no tiene un final natural.
• Un comportamiento inesperado del modelo o de la herramienta que, de otro modo, consumiría turnos ilimitados.

Un límite máximo de ejecución es un interruptor de circuito, no una prueba de que el flujo de trabajo sea correcto. Si la ejecución siempre se detiene al alcanzar dicho límite, aún existe un problema lógico que corregir.

2. Hacer que la finalización sea detectable por la máquina, no meramente conversacional.

La señal de terminación más fuerte es aquella que su aplicación puede reconocer sin interpretar texto. Si el flujo de trabajo tiene un evento de éxito claro, utilice la condición de terminación que más se ajuste. Por ejemplo, se puede detectar una transferencia específica con HandoffTermination, se puede detectar la finalización de una herramienta en particular con FunctionCallTermination, y se puede expresar lógica personalizada con FunctionalTermination.

Si utiliza esta función TextMentionTermination("TERMINATE"), defina claramente la responsabilidad: ¿qué agente está autorizado a declarar la finalización y bajo qué condición verificada? Evite dar instrucciones vagas a todos los participantes, como «continúe hasta quedar satisfecho». Este tipo de instrucciones puede generar un ciclo interminable de críticas y reescrituras, ya que el concepto de «satisfecho» carece de límites observables.

Un contrato de finalización útil es concreto: «El revisor emitirá TERMINAR solo cuando el borrador contenga las tres secciones requeridas y no quede ningún obstáculo pendiente». Mejor aún, cuando sea factible, haga que el revisor genere un estado estructurado que la aplicación pueda verificar.

3. Corrija el enrutamiento de SelectorGroupChat antes de reescribir todos los mensajes del agente.

SelectorGroupChatUtiliza un modelo para elegir al siguiente interlocutor del contexto de conversación compartido. La documentación estable señala que los nombres y descripciones de los participantes son importantes porque se utilizan en la selección del interlocutor. Por defecto, no se selecciona al mismo interlocutor consecutivamente a menos que sea el único agente disponible, aunque allow_repeated_speaker=Truecambia ese comportamiento. AutoGen también proporciona selector_funcy cuando se necesita un control más determinista. Consulte la documentacióncandidate_func oficial de SelectorGroupChat .

Si el mismo participante sigue siendo seleccionado, revise estos puntos en orden:

• Descripciones de los agentes: cada descripción debe indicar qué hace el agente y cuándo debe seleccionarse. Las descripciones superpuestas provocan inestabilidad en el enrutamiento.
• Mensaje del selector: mantenga las reglas de enrutamiento lo suficientemente cortas para que el modelo las aplique de forma fiable. La documentación de AutoGen recomienda explícitamente considerar un selector personalizado cuando el mensaje comience a acumular muchas condiciones.
• Configuración de repetición de voz: desactívela allow_repeated_speakera menos que sean realmente necesarios turnos consecutivos.
• Restricción de candidatos: si solo dos agentes son válidos después de un estado determinado, restrinja el conjunto de candidatos en lugar de pedirle al modelo que elija entre todos los participantes.
• Transiciones deterministas: úselas selector_funccuando el flujo de trabajo sea en realidad una máquina de estados disfrazada de conversación.

La distinción clave es sencilla: utilice la selección de interlocutor basada en LLM cuando el siguiente interlocutor requiera realmente un juicio semántico. Utilice el enrutamiento determinista cuando el siguiente interlocutor esté determinado por el estado del flujo de trabajo.

4. Evite las llamadas repetidas a herramientas haciendo visible el progreso.

En la versión actual de AgentChat, AssistantAgentexiste un max_tool_iterationsparámetro. La documentación de la API estable indica que el valor predeterminado es 1; al aumentarlo, el agente puede realizar llamadas secuenciales adicionales a la herramienta hasta que el modelo devuelva una respuesta de texto o se alcance el máximo. Esto significa que una sola ejecución del agente está limitada por esta configuración, pero el mismo agente puede ser seleccionado nuevamente por un equipo y repetir el mismo patrón de herramienta fallida en turnos posteriores. Consulte la referencia oficial de la API de AssistantAgent .

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

Si se repiten la misma herramienta y los mismos argumentos, reducir el límite de iteraciones solo minimiza el daño. La solución definitiva suele estar en el contrato de la herramienta. El modelo necesita información suficiente para determinar si la llamada se realizó correctamente, falló permanentemente, falló temporalmente o no generó información nueva.

Prefiero un resultado compacto y explícito como este:

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

Esto resulta más útil que una cadena genérica como «Sin resultado», ya que el modelo puede ver que repetir la misma llamada no supone ningún progreso. Para las herramientas con efectos secundarios, también conviene añadir idempotencia a nivel de aplicación para que una llamada repetida no pueda crear repetidamente el mismo ticket, pago, mensaje o modificación de la base de datos.

Compruebe también las llamadas a herramientas paralelas.

La AssistantAgentdocumentación de referencia estable indica que pueden ejecutarse varias llamadas a herramientas simultáneamente y que estas llamadas pueden deshabilitarse en los clientes de modelo compatibles. Asimismo, advierte que si se detectan varias transferencias, solo se ejecuta la primera, y recomienda deshabilitar las llamadas a herramientas en paralelo para evitar esta situación. Si su flujo de trabajo presupone transiciones de estado estrictas de una acción a la vez, las llamadas en paralelo pueden dificultar la comprensión del estado resultante.

5. Interrumpir el juego de pases rápidos en equipos estilo enjambre.

Un ciclo de transferencia suele funcionar así: el agente A decide que el agente B es más adecuado, el agente B percibe un contexto incompleto y devuelve la tarea, y ambas decisiones siguen siendo razonables a nivel local indefinidamente. El problema no radica en que ninguno de los modelos sea "incorrecto". La política de transferencia carece de propiedad y de un estado final.

Soluciónelo estableciendo una condición específica para cada transferencia y una regla que indique qué sucede cuando el destinatario no puede avanzar. Para flujos de trabajo interactivos con el usuario, HandoffTermination(target="user")está diseñado para detener al equipo cuando el control debe regresar a la aplicación o persona. La documentación de AutoGen sobre la intervención humana también explica que los flujos de trabajo de Swarm requieren un comportamiento de reanudación deliberado después de una transferencia de usuario. Consulte la documentación oficial sobre la intervención humana .

Un buen contrato de traspaso incluye:

• la capacidad exacta que posee el objetivo;
• la evidencia que justifica el traspaso;
• lo que el objetivo debería devolver si tiene éxito;
• qué debe hacer el objetivo si falta la información necesaria;
• una prohibición de devolver la tarea sin modificaciones.

6. Tratar los ciclos de GraphFlow como bucles reales que necesitan salidas explícitas.

GraphFlowAdmite ciclos deliberados, ramificación condicional y salidas de bucle. La API estable describe los bucles como válidos solo cuando existe una condición que finalmente los finaliza, y el constructor valida la estructura del grafo. También está marcada como experimental. Un bucle estructuralmente válido puede ejecutarse durante demasiado tiempo si la condición de salida es lógicamente inalcanzable, por lo que se recomienda mantener una condición de terminación independiente o un límite de giros. Consulte la referencia oficial de la API del equipo de AutoGen .

Esto es especialmente importante en diseños de tipo «redactor → revisor → redactor». Si se le indica al revisor que «siga mejorando hasta alcanzar la perfección», es posible que la condición de salida nunca se cumpla. Sustituya la perfección subjetiva por una rúbrica definida, como la presencia de las secciones requeridas, la superación de las comprobaciones de validación, la ausencia de defectos críticos y el número máximo de revisiones alcanzado.

7. Restablecer el estado cuando la siguiente tarea no esté relacionada.

Los agentes y equipos de AgentChat conservan el estado. La documentación estable de AutoGen indica que el equipo mantiene el contexto de la conversación entre ejecuciones para que las tareas relacionadas puedan continuar, y proporciona reset()la posibilidad de borrar el estado del equipo y de los participantes. Este comportamiento es útil para la continuidad, pero puede parecer un bucle si una tarea no relacionada hereda el contexto anterior, una delegación incompleta o suposiciones previas.

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

La API del agente estable también advierte a quienes llaman que solo envíen mensajes nuevos en cada llamada, en lugar de reproducir manualmente todo el historial de la conversación. Reintroducir el historial completo mientras el agente también mantiene el estado puede duplicar el contexto y reforzar comportamientos repetitivos.

8. Registra la transición, no solo el texto final.

Cuando un bucle sea difícil de reproducir, registre suficiente información para responder cuatro preguntas en cada turno: quién actuó, por qué fue seleccionado, qué acción intentó y qué cambió después. AutoGen proporciona soporte para el rastreo y la observabilidad, y la guía de rastreo estable muestra cómo rastrear equipos de AgentChat. Consulte la documentación oficial de rastreo de AutoGen .

Como mínimo, registre:

• Identificación de carrera y número de turno;
• Origen del mensaje y tipo de mensaje;
• Ponente seleccionado y candidatos disponibles;
• nombre de la herramienta más un hash o una forma normalizada de los argumentos;
• estado de la herramienta y si el estado cambió;
• Transferencia entre origen y destino;
• resultado de la condición de terminación;
• TaskResult.stop_reasoncuando termine la carrera.

Una herramienta de diagnóstico muy eficaz es la detección de "misma acción, mismo estado". Si el mismo agente invoca la misma herramienta con argumentos equivalentes y el hash del estado compartido no ha cambiado durante varias iteraciones, detenga la ejecución y márquela como un bucle sin progreso. Esta comprobación reside en la lógica de su aplicación, en lugar de ser una función integrada de AutoGen, pero detecta un tipo de fallos que los límites de tokens o mensajes solo registran a posteriori.

Una base de referencia práctica y segura

Para una aplicación AutoGen AgentChat existente, una línea base conservadora es:

• Configure siempre un mensaje fijo, un turno, un tiempo de espera o un límite de tokens.
• Combine ese límite con una condición de finalización significativa usando OR cuando cualquiera de las dos deba detener la ejecución.
• Manténgalo max_tool_iterationspequeño a menos que el agente realmente necesite una secuencia de herramientas de varios pasos.
• Devuelve resultados estructurados de la herramienta que distinguen entre éxito, falta de progreso, error que se puede reintentar y error permanente.
• No permita que se repitan las intervenciones de otros ponentes a menos que el flujo de trabajo lo requiera.
• Utilice selectores deterministas para flujos de trabajo deterministas.
• Asigne una propiedad explícita y una ruta terminal a las transferencias de datos.
• Reorganizar los equipos entre tareas no relacionadas.
• Rastrea los giros y detecta acciones repetidas con estado inalterado.

Qué no hacer

No resuelva todos los bucles simplemente aumentando el valor max_messagesde 25 a 100. Eso cambia el costo del fallo, no la lógica. No agregue un mensaje del sistema más largo antes de verificar si la condición de terminación está realmente integrada en el equipo. No permita que dos agentes sean responsables de la "revisión final". No devuelva cadenas de herramientas ambiguas si la siguiente llamada al modelo debe decidir si reintentar. Y no asuma que una ejecución que finalmente se detiene es correcta: un flujo de trabajo que siempre alcanza su límite de seguridad sigue presentando un mal funcionamiento.

Cuándo migrar en lugar de seguir aplicando parches

Si mantiene una aplicación AutoGen existente, estas correcciones son apropiadas y la documentación actual sigue disponible. Sin embargo, para un sistema nuevo o una reescritura importante de la orquestación, el estado de mantenimiento cambia la decisión. Microsoft ahora recomienda a los nuevos usuarios Microsoft Agent Framework, y su documentación de migración describe un cambio desde el núcleo y los equipos de alto nivel de AutoGen, basados ​​en eventos, hacia flujos de trabajo tipados y basados ​​en gráficos. Esto no significa que un bucle de AutoGen deba migrarse de inmediato, pero sí que debe sopesar el costo de un trabajo de orquestación más profundo y específico de AutoGen frente a la migración al sucesor compatible.

Por lo tanto, la ruta de depuración más corta y fiable es la siguiente: limitar la ejecución, identificar la transición repetitiva, hacer que el progreso sea observable y, finalmente, determinista la salida. Una vez implementados estos cuatro elementos, la mayoría de los bucles "infinitos" de AutoGen se convierten en errores de flujo de trabajo comunes que se pueden reproducir y corregir.

Referencias oficiales

• Repositorio Microsoft AutoGen : aviso de modo de mantenimiento actual.
• Lanzamientos de AutoGen : información sobre la versión estable de Python.
• Guía de finalización de AutoGen AgentChat .
• Guía de AutoGen SelectorGroupChat .
• Referencia de la API de AutoGen AssistantAgent .
• Guía de equipos de AutoGen .
• Guía de migración de Microsoft AutoGen a Agent Framework — actualizada el 25 de agosto de 2026.