Pourquoi votre agent AutoGen se retrouve bloqué dans des boucles infinies — et comment y remédier

Il est important de prendre en compte un changement de plateforme avant de déboguer une boucle AutoGen. Depuis septembre 2026, le dépôt officiel d'AutoGen est en mode maintenance : il bénéficiera de mises à jour correctives plutôt que de nouvelles fonctionnalités, et Microsoft recommande Microsoft Agent Framework pour les nouveaux projets. Le dépôt officiel d'AutoGen indique toujours Python 0.7.5 comme version stable actuelle, tandis que Microsoft a publié un guide de migration mis à jour d'AutoGen vers Agent Framework le 25 août 2026. Si vous utilisez déjà AutoGen en production, les techniques de dépannage ci-dessous restent néanmoins pertinentes. Consultez le dépôt officiel d'AutoGen , les versions officielles d'AutoGen et le guide de migration d'AutoGen de Microsoft .

Un agent AutoGen semble généralement bloqué dans une boucle infinie pour l'une des cinq raisons suivantes : l'exécution ne comporte aucune condition d'arrêt fiable, la politique de sélection du prochain intervenant choisit systématiquement un participant improductif, un appel d'outil ne produit aucun progrès visible, les agents effectuent des allers-retours manuels, ou l'application reprend constamment un état obsolète. La solution la plus rapide n'est pas de réécrire chaque invite. Commencez par identifier la boucle en question, puis ajoutez un point d'arrêt, et enfin corrigez la transition défaillante.

Diagnostic rapide : quel type de boucle observez-vous ?

1. Ajoutez un point d'arrêt brutal avant de déboguer quoi que ce soit d'autre.

AutoGen AgentChat intègre des conditions de terminaison afin de limiter les interactions entre les équipes. La documentation stable inclut les éléments suivants : [liste des éléments MaxMessageTerminationà TextMentionTerminationinsérer ] TokenUsageTermination. Consultez la documentation officielle d'AutoGen concernant la terminaison .TimeoutTerminationHandoffTerminationSourceMatchTerminationExternalTerminationStopMessageTerminationTextMessageTerminationFunctionCallTerminationFunctionalTermination

Pour la plupart des flux de production, utilisez une condition d'achèvement sémantique et un seuil de sécurité indépendant. L'opérateur important est généralement OU, car vous souhaitez que l'exécution s'arrête soit lorsque la tâche se termine normalement, soit lorsque le seuil de sécurité est atteint.

from autogen_agentchat.conditions import (
    MaxMessageTermination,
    TextMentionTermination,
)

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

termination = done | safety_cap

Une erreur fréquente consiste à se fier uniquement à l'instruction « Terminer une fois terminé ». Cela laisse la correction du comportement au modèle. Une autre erreur est de combiner des conditions alors &qu'on veut en réalité dire « s'arrêter à l'une ou l'autre condition ». AutoGen prend en charge les combinaisons ET et OU ; choisissez donc la sémantique avec soin.

Ce que cela répare

• Une équipe qui ne produit jamais la phrase de conclusion attendue.
• Un sélecteur qui continue de trouver un autre haut-parleur même lorsque toute activité utile est terminée.
• Une chaîne de transmission sans fin naturelle.
• Un comportement inattendu du modèle ou de l'outil qui, autrement, consommerait un nombre illimité de tours.

Une limite de fonctionnement est un disjoncteur, pas une preuve que le flux de travail est correct. Si le traitement s'arrête systématiquement à cause de cette limite, il y a toujours un problème de logique à résoudre.

2. Rendre la complétion détectable par machine, et pas seulement conversationnelle.

Le signal de fin le plus pertinent est celui que votre application peut reconnaître sans avoir à interpréter le texte. Si le flux de travail comporte un événement de réussite clair, utilisez la condition de fin la plus appropriée. Par exemple, un transfert spécifique peut être détecté avec `<transfert>` HandoffTermination, la fin d'un outil particulier avec `<terminate>` FunctionCallTermination, et une logique personnalisée peut être exprimée avec `<terminate>` FunctionalTermination.

Si vous utilisez cette méthode TextMentionTermination("TERMINATE"), précisez les responsabilités : quel agent est autorisé à déclarer la tâche terminée et sous quelles conditions vérifiées ? Évitez de donner à chaque participant des instructions vagues telles que « continuez jusqu’à satisfaction ». Ce type d’instruction peut engendrer des critiques et des réécritures interminables, car la notion de « satisfaction » n’a pas de limite observable.

Un contrat de finalisation utile est concret : « Le réviseur émet le signal TERMINATE uniquement lorsque le brouillon contient les trois sections requises et qu’aucun blocage n’est plus présent. » Mieux encore, lorsque cela est possible, exigez que le réviseur produise un état structuré que l’application puisse vérifier.

3. Corriger le routage de SelectorGroupChat avant de réécrire toutes les invites des agents

SelectorGroupChatUtilise un modèle pour choisir le prochain intervenant dans le contexte de la conversation partagée. La documentation stable précise que les noms et descriptions des participants sont importants car ils servent à la sélection de l'intervenant. Par défaut, un même intervenant n'est pas sélectionné consécutivement, sauf s'il est le seul agent disponible ; allow_repeated_speaker=Truece comportement peut toutefois être modifié. AutoGen offre également selector_funcdes fonctionnalités supplémentaires pour un contrôle plus précis. Consultez la documentationcandidate_func officielle de SelectorGroupChat .

Si le même participant est sélectionné à plusieurs reprises, vérifiez les points suivants dans l'ordre :

• Descriptions des agents : chaque description doit préciser le rôle de l’agent et les situations dans lesquelles il convient d’être sélectionné. Des descriptions qui se chevauchent rendent le routage instable.
• Invite de sélection : veillez à ce que les règles de routage restent suffisamment courtes pour que le modèle s’applique correctement. La documentation d’AutoGen recommande explicitement d’envisager un sélecteur personnalisé lorsque l’invite commence à contenir de nombreuses conditions.
• Réglage des haut-parleurs répétés : à allow_repeated_speakerdésactiver sauf si des interventions consécutives sont réellement nécessaires.
• Restriction des candidats : si seulement deux agents sont valides après un état particulier, restreignez l’ensemble des candidats plutôt que de demander au modèle de choisir parmi tous les participants.
• Transitions déterministes : à utiliser selector_funclorsque le flux de travail est en réalité une machine à états déguisée en conversation.

La principale distinction est simple : utilisez la sélection du locuteur basée sur le modèle LLM lorsque le prochain locuteur nécessite réellement un jugement sémantique ; utilisez le routage déterministe lorsque le prochain locuteur est déterminé par l’état du flux de travail.

4. Mettez fin aux appels d'outils répétitifs en rendant la progression visible.

Dans la version actuelle d'AgentChat, AssistantAgentun max_tool_iterationsparamètre est disponible. La documentation de l'API stable indique que sa valeur par défaut est 1 ; lorsqu'elle est augmentée, l'agent peut effectuer des appels d'outils séquentiels supplémentaires jusqu'à ce que le modèle renvoie une réponse textuelle ou que la limite maximale soit atteinte. Cela signifie qu'une exécution d'agent est limitée par ce paramètre, mais le même agent peut être sélectionné à nouveau par une équipe et répéter le même schéma d'outils ayant échoué lors de différents tours. Consultez la documentation officielle de l'API AssistantAgent .

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

Si vous utilisez systématiquement le même outil et les mêmes arguments, réduire la limite d'itérations ne fait que masquer le problème. La solution réside généralement dans le contrat de l'outil. Le modèle a besoin de suffisamment d'informations pour déterminer si l'appel a réussi, a échoué définitivement, a échoué temporairement ou n'a produit aucune information nouvelle.

Privilégiez un résultat concis et explicite tel que :

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

Cette formulation est plus utile qu'une chaîne générique comme « Aucun résultat », car le modèle comprend que répéter le même appel ne constitue pas une progression. Pour les outils à effets de bord, il est également important d'ajouter l'idempotence au niveau de l'application afin qu'un appel répété ne puisse pas créer systématiquement le même ticket, paiement, message ou modification de base de données.

Vérifiez également les appels d'outils parallèles

La AssistantAgentdocumentation de référence indique que plusieurs appels d'outils peuvent s'exécuter simultanément et que les appels d'outils parallèles peuvent être désactivés dans les clients de modèles compatibles. Elle précise également que si plusieurs transferts sont détectés, seul le premier est exécuté et recommande de désactiver les appels d'outils parallèles pour éviter cette situation. Si votre flux de travail suppose des transitions d'état strictes, une action à la fois, les appels parallèles peuvent rendre l'état résultant plus difficile à interpréter.

5. Briser le jeu de relais en équipes de type Swarm

Une boucle de transfert se déroule généralement ainsi : l’agent A estime que l’agent B est plus approprié, l’agent B constate un contexte incomplet et renvoie la tâche, et les deux choix restent valables localement. Le problème n’est pas qu’un modèle soit « faux ». La politique de transfert manque de définition de la responsabilité et d’état final.

Corrigez ce problème en définissant une condition précise pour chaque transfert et une règle pour le comportement lorsque la cible ne peut pas progresser. Pour les flux de travail interactifs, le système HandoffTermination(target="user")est conçu pour interrompre l'équipe lorsque le contrôle doit être rendu à l'application ou à la personne. La documentation d'AutoGen sur l'intervention humaine explique également que les flux de travail Swarm nécessitent un comportement de reprise explicite après un transfert utilisateur. Consultez la documentation officielle sur l'intervention humaine .

Un bon contrat de passation de pouvoir comprend :

• la capacité exacte que possède la cible ;
• les preuves qui justifient le transfert ;
• ce que la cible doit renvoyer en cas de succès ;
• que la cible doit faire si les informations requises sont manquantes ;
• interdiction de renvoyer la tâche sans modification.

6. Traitez les cycles GraphFlow comme de véritables boucles nécessitant des sorties explicites.

GraphFlowCe module prend en charge les cycles intentionnels, les branchements conditionnels et les sorties de boucle. L'API stable définit les boucles comme valides uniquement lorsqu'une condition permet d'en sortir, et le générateur valide la structure du graphe. Ce module est également marqué comme expérimental. Une boucle structurellement valide peut néanmoins s'exécuter indéfiniment si la condition de sortie est logiquement inaccessible ; il est donc recommandé de définir une condition d'arrêt indépendante ou de limiter son exécution. Consultez la documentation de l'API officielle des équipes AutoGen .

Cela est particulièrement important dans les processus de type « rédacteur → relecteur → rédacteur ». Si le relecteur a pour consigne d’« améliorer sans cesse jusqu’à la perfection », cet objectif risque de ne jamais être atteint. Il est préférable de remplacer la recherche subjective de la perfection par des critères précis, tels que la présence des sections requises, la réussite des tests de validation, l’absence de défauts critiques et le nombre maximal de révisions atteint.

7. Réinitialiser l'état lorsque la tâche suivante est sans rapport.

Les agents et les équipes d'AgentChat conservent un état. La documentation stable d'AutoGen indique que l'équipe conserve le contexte de conversation entre les exécutions afin que les tâches associées puissent se poursuivre, et qu'il est possible reset()d'effacer l'état de l'équipe et des participants. Ce comportement est utile pour la continuité, mais peut donner l'impression d'une boucle si une tâche sans lien avec la précédente hérite d'un ancien contexte, d'une délégation inachevée ou d'hypothèses antérieures.

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

L'API stable de l'agent avertit également les appelants de ne transmettre que les nouveaux messages à chaque appel, plutôt que de rejouer manuellement l'intégralité de l'historique de la conversation. Réinjecter l'historique complet, alors que l'agent conserve également son état, peut dupliquer le contexte et renforcer les comportements répétitifs.

8. Consignez la transition, et pas seulement le texte final.

Lorsqu'une boucle est difficile à reproduire, enregistrez suffisamment d'informations pour répondre à quatre questions à chaque tour : qui a agi, pourquoi cette personne a été sélectionnée, quelle action elle a tentée et qu'est-ce qui a changé ensuite ? AutoGen offre une prise en charge du traçage et de l'observabilité, et le guide de traçage stable présente le traçage des équipes AgentChat. Consultez la documentation officielle d'AutoGen sur le traçage .

Au minimum, journaliser :

• Identifiant de la course et numéro de tour ;
• source et type du message ;
• conférencier sélectionné et candidats disponibles ;
• nom de l'outil plus une forme hachée ou normalisée des arguments ;
• état de l'outil et indication de changement d'état ;
• source et cible de transfert ;
• résultat de la condition de terminaison ;
• TaskResult.stop_reasonlorsque la course se termine.

Un diagnostic très efficace consiste à détecter les actions répétées dans un même état. Si un même agent invoque le même outil avec des arguments identiques et que le hachage d'état partagé reste inchangé pendant plusieurs itérations, interrompez l'exécution et signalez-la comme une boucle infinie. Cette vérification, qui relève de la logique de votre application et n'est pas une fonctionnalité intégrée d'AutoGen, permet de détecter certaines défaillances que les limites de jetons ou de messages ne repèrent qu'a posteriori.

Une base de référence pratique et sûre

Pour une application AutoGen AgentChat existante, une base de référence prudente est :

• Configurez toujours une limite stricte pour les messages, les délais d'expiration ou le nombre de jetons.
• Combinez ce plafond avec une condition d'achèvement significative en utilisant OU lorsque l'un ou l'autre doit arrêter l'exécution.
• Limitez max_tool_iterationsla taille des outils à moins que l'agent n'ait réellement besoin d'une séquence d'outils en plusieurs étapes.
• Retourner des résultats d'outils structurés qui distinguent la réussite, l'absence de progrès, l'erreur pouvant être corrigée et l'erreur permanente.
• N’autorisez pas la répétition des mêmes intervenants, sauf si le flux de travail l’exige.
• Utilisez des sélecteurs déterministes pour les flux de travail déterministes.
• Attribuez explicitement la propriété et un itinéraire terminal aux transferts.
• Réinitialiser les équipes entre les tâches non liées.
• Suivre les virages et détecter les actions répétées sans modification de l'état.

Ce qu'il ne faut pas faire

Ne résolvez pas chaque boucle en augmentant simplement la valeur max_messagesde 25 à 100. Cela modifie le coût de l'échec, pas la logique. N'ajoutez pas d'invite système plus longue avant de vérifier si la condition d'arrêt est bien intégrée à l'équipe. Ne laissez pas deux agents se partager la responsabilité de la « révision finale ». Ne renvoyez pas de chaînes d'outils ambiguës si l'appel de modèle suivant doit décider s'il faut réessayer. Et ne présumez pas qu'une exécution qui finit par s'arrêter est saine : un flux de travail qui atteint systématiquement sa limite de sécurité dysfonctionne toujours.

Quand migrer plutôt que de continuer à corriger les problèmes

Si vous gérez une application AutoGen existante, ces correctifs sont appropriés et la documentation actuelle reste disponible. En revanche, pour un nouveau système ou une refonte majeure de l'orchestration, le passage au mode maintenance modifie la décision. Microsoft oriente désormais les nouveaux utilisateurs vers Microsoft Agent Framework, et sa documentation de migration décrit une transition des équipes événementielles d'AutoGen vers des flux de travail typés et basés sur des graphes. Cela ne signifie pas qu'une boucle AutoGen doit être migrée immédiatement, mais il est important d'évaluer le coût d'une orchestration plus poussée spécifique à AutoGen par rapport à la migration vers la solution de remplacement prise en charge.

La méthode de débogage fiable la plus courte consiste donc à : délimiter la durée d'exécution, identifier la transition répétitive, rendre la progression observable, puis rendre la sortie déterministe. Une fois ces quatre éléments en place, la plupart des boucles AutoGen « infinies » deviennent des bogues de flux de travail ordinaires, reproductibles et corrigibles.

Références officielles

• Référentiel Microsoft AutoGen — avis de mode de maintenance actuel.
• AutoGen publie des informations sur les versions stables de Python.
• Guide de résiliation d'AutoGen AgentChat .
• Guide AutoGen SelectorGroupChat .
• Référence de l'API AutoGen AssistantAgent .
• Guide des équipes AutoGen .
• Guide de migration de Microsoft AutoGen vers Agent Framework — mis à jour le 25 août 2026.