CrewAI : construire une équipe d’agents IA collaboratifs

Un seul agent qui fait tout — comprendre, chercher, rédiger — finit par bâcler. Demandez à une même personne d’enquêter et de soigner la rédaction sous pression : l’un des deux en pâtit. La coopérative Teranga le constate : ses réponses générées sont exactes mais sèches, ou bien chaleureuses mais imprécises. La solution n’est pas un modèle plus gros, c’est une équipe : un agent qui rassemble les faits, un autre qui les met en forme.

C’est la philosophie de CrewAI : composer une « équipe » (crew) d’agents spécialisés, chacun avec un rôle, un objectif et une personnalité, à qui l’on confie des tâches qui s’enchaînent. Là où LangGraph vous fait dessiner un graphe, CrewAI vous fait recruter des collègues virtuels. Dans ce tutoriel, on monte une petite équipe qui rédige les réponses du support client.

🎯 Ce que vous allez apprendre

• Définir des agents CrewAI avec un rôle, un objectif et une histoire (backstory).
• Décrire des tâches et les confier aux bons agents.
• Assembler une Crew et la lancer avec kickoff.
• Choisir entre un processus séquentiel et hiérarchique.

🛠️ Ce que vous allez construire

Une équipe de deux agents pour l’Assistant Teranga : un Analyste qui lit la question du client et liste les faits utiles, et un Rédacteur qui transforme ces faits en une réponse chaleureuse et juste, en français. Vous donnez la question, l’équipe vous rend une réponse prête à envoyer.

Prérequis

• Python 3.10+ (CrewAI exige la 3.10 ou plus). Installez : pip install -U crewai (au moment d’écrire, la 1.x).
• Une clé d’API (variable OPENAI_API_KEY) ou Ollama pour rester en local.
• Test express : si vous savez écrire une fonction et une classe en Python, vous êtes prêt — CrewAI est très déclaratif.
• ⏱️ Temps estimé : ~45 minutes.

Étape 1 — Définir le modèle et les agents

Un agent CrewAI se décrit en langage presque naturel. Trois champs comptent : le rôle (qui il est), l’objectif (ce qu’il vise) et la backstory (son expérience, qui colore son style). Ces textes ne sont pas décoratifs : ils deviennent le prompt système de chaque agent et façonnent vraiment ses réponses. On configure le modèle une fois via la classe LLM.

from crewai import Agent, Task, Crew, Process, LLM

modele = LLM(model="openai/gpt-4o-mini", temperature=0.3)
# Variante locale : LLM(model="ollama/llama3.1", base_url="http://localhost:11434")

analyste = Agent(
    role="Analyste du support Teranga",
    goal="Lister précisément les faits nécessaires pour répondre à la question d'un client",
    backstory=("Tu connais par cœur le catalogue, les délais de livraison et les conditions "
               "de la coopérative. Tu es rigoureux et tu ne supposes jamais un chiffre."),
    llm=modele,
    verbose=True,
)

redacteur = Agent(
    role="Rédacteur du support Teranga",
    goal="Écrire une réponse client chaleureuse, claire et exacte en français",
    backstory=("Ancien vendeur en boutique, tu sais parler aux clients avec courtoisie "
               "et simplicité, sans jargon, en allant droit au but."),
    llm=modele,
    verbose=True,
)

Le temperature=0.3 garde l’Analyste factuel ; on pourrait monter un peu pour le Rédacteur si on veut plus de chaleur. Le verbose=True affiche le raisonnement de chaque agent dans la console — précieux pour comprendre qui fait quoi pendant l’exécution.

✅ Point d’étape — vos deux agents sont définis sans erreur d’import. Si crewai est introuvable, vérifiez l’installation et la version de Python (3.10+).

Étape 2 — Décrire les tâches

Un agent sans tâche ne fait rien. Une Task précise ce qu’il faut produire (description), le résultat attendu (expected_output) et qui s’en charge (agent). Le détail malin : la description peut contenir des variables entre accolades, remplies au lancement — ainsi la même équipe traite n’importe quelle question.

analyse = Task(
    description=("Analyse la question du client : « {question} ». "
                 "Liste sous forme de points les faits nécessaires pour y répondre "
                 "(produit concerné, prix, stock, délai, livraison). Ne réponds pas au client."),
    expected_output="Une liste de faits vérifiés, sans phrase de politesse.",
    agent=analyste,
)

redaction = Task(
    description=("À partir des faits fournis, rédige LA réponse à envoyer au client, "
                 "en français, chaleureuse et concise (3 à 5 phrases). "
                 "N'invente aucun fait absent de l'analyse."),
    expected_output="Le texte final de la réponse client, prêt à envoyer.",
    agent=redacteur,
)

La tâche de rédaction s’appuie sur le résultat de l’analyse : en processus séquentiel, CrewAI passe automatiquement la sortie d’une tâche comme contexte à la suivante. C’est ce relais qui fait travailler les deux agents ensemble, comme un binôme qui se passe un dossier.

✅ Point d’étape — chaque tâche est rattachée au bon agent (analyse → analyste, rédaction → rédacteur). Un mauvais rattachement et c’est le rédacteur qui enquête, l’analyste qui rédige.

Étape 3 — Assembler et lancer l’équipe

On rassemble agents et tâches dans une Crew, on choisit un processus, et on lance avec kickoff en injectant la question. Le processus sequential exécute les tâches dans l’ordre déclaré — exactement notre besoin : analyser, puis rédiger.

equipe = Crew(
    agents=[analyste, redacteur],
    tasks=[analyse, redaction],
    process=Process.sequential,
    verbose=True,
)

resultat = equipe.kickoff(inputs={"question":
    "Bonjour, le panier en osier moyen est-il dispo et livrable à Bobo cette semaine ?"})
print(resultat)   # la réponse finale = sortie de la dernière tâche

Le {question} de la description est remplacé par la valeur passée dans inputs. L’Analyste produit sa liste de faits, le Rédacteur s’en sert pour écrire la réponse, et kickoff renvoie la sortie de la dernière tâche : le message prêt à envoyer. Vous venez de faire collaborer deux agents sans écrire une seule ligne d’orchestration manuelle.

✅ Point d’étape — print(resultat) affiche une réponse client complète et polie. Si elle est sèche ou inexacte, ajustez les backstories ou les expected_output avant de toucher au code.

Pourquoi spécialiser plutôt que tout demander ?

On pourrait objecter : un bon modèle ne sait-il pas analyser et rédiger dans un seul prompt ? Si, en théorie. Mais en pratique, une consigne unique qui demande « trouve les faits, vérifie-les, puis écris une belle réponse » dilue l’attention du modèle : il bâcle souvent l’une des étapes. Découper en agents, c’est donner à chacun une consigne courte et un seul objectif — et un modèle concentré sur une tâche la réussit mieux qu’un modèle tiraillé entre trois. C’est aussi plus maintenable : si les réponses manquent de chaleur, vous savez exactement quel agent retoucher, sans risquer de casser l’analyse. La spécialisation n’est pas qu’une élégance d’architecture, c’est un gain concret de qualité et de débogage.

Séquentiel ou hiérarchique ?

CrewAI propose deux façons de faire travailler l’équipe. Le séquentiel, qu’on vient d’utiliser, enchaîne les tâches dans l’ordre : simple, prévisible, idéal quand le flux est clair (analyser puis rédiger). Le hiérarchique introduit un agent manager qui décide lui-même quel agent mobiliser, dans quel ordre, et peut répartir le travail dynamiquement. On l’active avec process=Process.hierarchical en fournissant un manager_llm. Réservez-le aux cas où l’enchaînement n’est pas connu d’avance : un manager qui, selon la demande, sollicite tantôt l’expert livraison, tantôt l’expert produit. Pour un binôme analyse-rédaction au flux fixe, le séquentiel reste le bon choix — plus simple, moins cher, plus contrôlable.

CrewAI ou LangGraph : lequel pour quoi ?

Les deux orchestrent plusieurs étapes, mais avec un état d’esprit différent. LangGraph raisonne en graphe : vous contrôlez finement chaque transition, idéal quand la logique métier est stricte (validation humaine, branches conditionnelles, boucles de vérification). CrewAI raisonne en équipe : vous décrivez des rôles et laissez les agents collaborer, idéal quand la valeur vient de la division du travail (un chercheur, un rédacteur, un relecteur). En pratique : choisissez LangGraph quand vous voulez maîtriser le parcours, CrewAI quand vous voulez répartir des compétences. Et rien n’empêche de combiner : un nœud LangGraph peut lancer une crew CrewAI. Le bon outil dépend de la question « ai-je un parcours à contrôler, ou des rôles à distribuer ? ».

Au-delà des crews : les Flows

Quand vous avez besoin d’un contrôle plus déterministe — déclencher une crew seulement si une condition est remplie, enchaîner plusieurs crews — CrewAI propose les Flows, une couche d’orchestration événementielle (avec des étapes de départ et des réactions). C’est l’équivalent CrewAI d’un graphe : on garde la collaboration entre agents, mais on reprend la main sur l’enchaînement global. Gardez cette piste en tête pour plus tard ; pour un premier projet, une crew séquentielle suffit largement.

Donner des outils à l’équipe

Nos deux agents raisonnent à partir de ce que le modèle sait déjà ou de ce qu’on leur passe. Mais comme un agent LangChain, un agent CrewAI peut recevoir des outils pour aller chercher l’information à la source. On les passe via le paramètre tools de l’Agent : l’Analyste pourrait alors interroger réellement la base de commandes au lieu de se fier au contexte.

from crewai_tools import SerperDevTool   # recherche web ; il en existe beaucoup d'autres

analyste = Agent(
    role="Analyste du support Teranga",
    goal="Lister les faits nécessaires en s'appuyant sur des sources réelles",
    backstory="Tu vérifies chaque fait avant de l'avancer.",
    tools=[SerperDevTool()],   # ou vos propres outils maison
    llm=modele, verbose=True,
)

Le paquet crewai_tools fournit des outils prêts à l’emploi (recherche, lecture de fichiers, requêtes), et vous pouvez écrire les vôtres exactement comme dans le tutoriel sur le tool calling. C’est ce qui fait passer une équipe d’un exercice de rédaction à un véritable assistant branché sur vos données — un Analyste qui consulte la vraie base ne risque plus de raisonner sur un contexte périmé.

La mémoire d’équipe

Par défaut, une crew oublie tout d’un appel à l’autre. CrewAI propose d’activer une mémoire partagée pour que l’équipe se souvienne des échanges et des préférences au fil des interactions — utile pour un assistant qui suit un même client dans le temps. On l’active d’un paramètre.

equipe = Crew(
    agents=[analyste, redacteur],
    tasks=[analyse, redaction],
    process=Process.sequential,
    memory=True,   # l'équipe conserve une mémoire entre les exécutions
    verbose=True,
)

Avec la mémoire activée, l’équipe peut, par exemple, se rappeler qu’un client habite Bobo-Dioulasso et adapter spontanément ses réponses sur la livraison. C’est l’équivalent, côté CrewAI, du checkpointer de LangGraph : la différence entre un assistant amnésique et un assistant qui construit une relation. Réservez-la toutefois aux cas où ce suivi apporte une vraie valeur, car elle ajoute des appels et de la complexité.

🐞 Pièges fréquents

🌍 Adaptation au contexte ouest-africain

Une équipe d’agents consomme plusieurs appels de modèle par requête (un par tâche, parfois plus) : c’est plus riche, mais plus cher qu’un agent unique. Le bon réflexe : réservez CrewAI aux tâches à forte valeur (rédiger une réponse soignée, préparer un devis) et gardez un simple agent ou une chaîne pour les questions répétitives. Pendant le développement, branchez Ollama en local pour itérer sans facture. Et soignez les backstories en français : un agent dont le rôle est décrit clairement produit du premier coup ce que vous attendez, ce qui réduit les allers-retours — donc les appels — et accélère la mise au point sur une connexion lente.

✅ Récapitulatif

Vous savez maintenant composer une équipe d’agents : définir des rôles distincts avec leur objectif et leur histoire, leur confier des tâches qui s’enchaînent, assembler une Crew et la lancer avec kickoff. L’Assistant Teranga ne repose plus sur un généraliste débordé, mais sur un binôme — un analyste rigoureux et un rédacteur chaleureux — qui produit des réponses à la fois exactes et agréables. C’est la force du multi-agent : diviser pour mieux répondre.

🧾 Aide-mémoire

💪 À vous de jouer

Ajoutez un troisième agent Relecteur chargé de vérifier que la réponse du rédacteur ne contient aucun fait absent de l’analyse, et de la corriger sinon. Ajoutez sa tâche à la fin de la chaîne.

relecteur = Agent(
    role="Relecteur qualité Teranga",
    goal="Garantir que la réponse ne contient que des faits issus de l'analyse",
    backstory="Méticuleux, tu traques la moindre affirmation non sourcée.",
    llm=modele, verbose=True,
)

relecture = Task(
    description=("Compare la réponse rédigée à la liste de faits de l'analyse. "
                 "Supprime ou corrige toute affirmation non justifiée. Rends la version finale."),
    expected_output="La réponse client validée, sans fait inventé.",
    agent=relecteur,
)

equipe = Crew(agents=[analyste, redacteur, relecteur],
              tasks=[analyse, redaction, relecture],
              process=Process.sequential, verbose=True)

Tutoriels frères

• LangGraph : agents à états et cycles — orchestrer un parcours sur mesure.
• Donner des outils à un agent (tool calling) — connecter les agents à de vraies actions.

Pour aller plus loin

• 🔝 Retour au guide principal : le guide des frameworks d’agents IA
• Documentation officielle : les crews CrewAI
• À lire ensuite : observabilité, mémoire et mise en production.

FAQ

Q : CrewAI dépend-il de LangChain ?
R : Non, c’est un framework indépendant, avec sa propre logique d’agents et de tâches. Il s’utilise seul ; on peut néanmoins le combiner avec LangChain ou LangGraph dans un projet plus large.

Q : Combien d’agents mettre dans une équipe ?
R : Commencez à deux ou trois, avec des rôles vraiment distincts. Trop d’agents multiplie les appels (donc le coût) sans gain si les rôles se recouvrent. La bonne équipe est la plus petite qui couvre les compétences nécessaires.

Q : Les agents CrewAI peuvent-ils utiliser des outils ?
R : Oui, on leur passe des outils via le paramètre tools (par exemple ceux du paquet crewai_tools, ou les vôtres). Un agent peut alors chercher sur le web, lire un fichier ou interroger votre base, comme dans le tutoriel sur le tool calling.

Q : Quand préférer CrewAI à un seul agent LangChain ?
R : Quand la qualité vient de la division du travail. Pour une réponse simple, un agent suffit. Pour une production en plusieurs métiers (rechercher, rédiger, relire), une équipe donne un meilleur résultat — au prix de quelques appels supplémentaires.