Module 9 — Débogage d'une équipe qui n'aboutit pas

Une équipe CrewAI qui échoue le fait rarement avec une belle exception rouge. Elle tourne, produit du texte, épuise ses itérations et rend un livrable médiocre — sans que rien ne signale l'anomalie. Ce module fournit les gestes concrets pour transformer cette panne silencieuse en diagnostic précis, à partir de la trace verbose=True.

Lire une trace, dans le bon ordre

Une trace CrewAI se lit du haut vers le bas, en repérant trois types de lignes.

Les entêtes de tâche annoncent le début d'une tâche, avec l'agent affecté et la description. Elles délimitent des sections que l'on peut lire indépendamment.

Les appels d'outils sont préfixés Using tool: nom_outil et suivis d'un Tool output: en plusieurs lignes. Le mauvais outil appelé au mauvais moment est le premier signal à chercher : un rédacteur qui appelle un outil de lecture de spécifications alors qu'il a déjà la sortie de l'analyste indique un problème d'attribution (module 5) ou une consigne floue.

Les conclusions d'agent apparaissent en Final Answer: et livrent le résultat de la tâche. Les comparer à l'expected_output de la tâche est l'exercice le plus rentable du débogage.

Trois lectures suffisent, en pratique, à localiser la majorité des défauts.

Les cinq pannes les plus fréquentes

Voici la table à imprimer et à garder près de vous. Chaque ligne identifie une pathologie fréquente, son signe dans la trace et le correctif immédiat.

Symptôme dans la trace	Cause probable	Correctif
L'agent conclut avec « Voici trois propositions… » quand une seule était attendue	expected_output trop vague sur le volume	Préciser dans expected_output : « Un seul livrable, pas plusieurs »
Deux agents s'échangent des messages Delegate work sans progrès	Objectifs redondants ou aucune autorité de conclusion	Nommer un responsable qui ne délègue pas, différencier les objectifs
Le rédacteur invente des noms de fonctionnalité qui n'existent pas	Contexte manquant (l'analyste n'a pas passé la liste)	Ajouter context=[tache_analyse] explicite, préciser la sortie attendue
Une tâche dure trois minutes et fait dix appels d'outils identiques	Outil mal décrit ou args_schema accepte trop	Réécrire la description de l'outil, resserrer les paramètres
L'exécution s'arrête sur « Agent stopped after max iterations »	Boucle interne d'un agent (auto-critique en spirale)	Baisser max_iter pour le voir tôt, corriger l'objectif qui n'aboutit pas

Ces cinq pannes couvrent facilement 80 % des équipes qui « ne marchent pas ». Elles ont deux racines communes : des définitions d'agents floues et des sorties attendues imprécises. C'est pourquoi les modules 2 et 3 sont les modules les plus importants du cours.

Le geste qui débloque presque toujours

Face à une équipe qui produit un livrable médiocre, un geste simple débloque presque toujours : rendre la sortie attendue plus précise. Reprenez la expected_output de la tâche fautive et transformez chaque adjectif en critère mesurable.

Avant :

« Une documentation claire et bien structurée. »

Après :

« Un document Markdown de 8 à 10 sections, chaque section commençant par un titre H2, contenant 200 à 400 mots, avec au moins un bloc de code fonctionnel dans les sections techniques. Pas d'introduction générale, pas de conclusion générale : chaque section est autonome. »

Cette réécriture est ennuyeuse. Elle est aussi le seul geste connu qui rende le comportement des agents reproductible. Aucun réglage de température, aucun changement de modèle et aucun changement de processus ne compense une sortie attendue vague.

Isoler pour diagnostiquer

Quand la panne persiste malgré des sorties attendues précises, l'étape suivante est d'isoler chaque tâche. CrewAI permet de créer une équipe minimale à un seul agent et une seule tâche pour reproduire le défaut :

mini_equipe = Crew(
    agents=[relecteur],
    tasks=[Task(
        description=(
            "Relis le document ci-joint et liste les affirmations non "
            "sourcées. Ignore le style."
        ),
        expected_output=(
            "Une liste numérotée d'au moins trois entrées, chaque entrée "
            "contenant la citation exacte et la raison de la sélection."
        ),
        agent=relecteur,
    )],
    process=Process.sequential,
    verbose=True,
)

mini_equipe.kickoff(inputs={"document": DOCUMENT_DE_TEST})

Cette réduction permet de valider chaque tâche séparément. Si le relecteur fonctionne bien isolé mais échoue en équipe, le défaut est dans le contexte transmis — pas dans l'agent. Si l'inverse est vrai, le défaut est dans la définition de l'agent.

Piéger la variabilité

Une équipe qui donne un bon livrable une fois sur trois n'est pas une équipe qui marche. Le geste minimal pour objectiver la variabilité est de lancer dix exécutions consécutives sur la même entrée et de mesurer :

• le taux d'aboutissement (livrable produit sans exception) ;
• le coût médian et son écart-type ;
• la qualité évaluée par un critère fixe — nombre de sections attendues présentes, présence des blocs de code, mots-clés du glossaire respectés.

Une équipe est « en production » quand ces trois nombres sont stables sur dix exécutions. Tant qu'ils ne le sont pas, l'équipe est un prototype — et l'utiliser sur du trafic réel expose à des livrables aléatoires facturés au client.

Le journal de bord des équipes

Tenez un fichier debogage.md par équipe où vous notez chaque exécution problématique, la trace résumée, la correction appliquée et le résultat. En quelques semaines, ce journal devient votre référence : vous reconnaissez un symptôme et vous appliquez la correction sans repartir de zéro.

En résumé

• Une trace verbose=True se lit en repérant trois types de lignes : entêtes de tâche, appels d'outils, conclusions d'agent.
• Cinq pannes couvrent 80 % des cas : sortie vague, boucle de délégation, contexte manquant, outil mal décrit, max_iter atteint.
• Le geste qui débloque presque toujours est de préciser la expected_output — transformer les adjectifs en critères mesurables.
• Isolez chaque tâche dans une mini-équipe à un agent pour localiser un défaut, et mesurez la variabilité sur dix exécutions avant de parler de production.

Module suivant : le projet complet, une équipe de rédaction qui livre une documentation évaluable.