Comment utiliser CrewAI : Un guide pratique des flux de travail multi-agents
Promesse audacieuse : Si vous avez déjà souhaité pouvoir cloner votre meilleur coéquipier pour mener à bien un projet plus rapidement, CrewAI vous en rapproche en orchestrant plusieurs agents d'IA qui planifient, collaborent et livrent le travail ensemble.
Dans ce guide pratique et axé sur les solutions, vous apprendrez exactement comment utiliser CrewAI : de l'installation du framework et de la définition des agents à la construction de rôles, d'outils, de tâches et de flux de travail multi-agents structurés qui produisent de véritables résultats. Nous couvrirons les modèles de recherche, de contenu, d'analyse de données et de génération de code, et comment éviter les pièges courants tels que les impasses d'agents, le gonflement des invites et le dépassement de la portée des outils.
Notre objectif : vous donner un chemin « essayez-le aujourd'hui » étape par étape avec du code copier-coller, des meilleures pratiques éprouvées et quelques modèles de flux de travail que vous pouvez adapter. Que vous automatisiez des études de marché ou que vous construisiez une spécification de produit à partir de tickets, voici votre rampe d'accès pour utiliser CrewAI efficacement.
Qu'est-ce que CrewAI (et pourquoi est-ce différent)
- CrewAI est un framework pour construire des systèmes multi-agents où chaque agent a un rôle, un objectif, des outils et des règles. Le framework coordonne ensuite ces agents, en transmettant les tâches, en partageant le contexte et en itérant vers un résultat.
- Contrairement à une seule invite de LLM, CrewAI impose une structure : les agents sont explicites, les tâches sont modulaires, les outils sont autorisés et les résultats sont vérifiables.
- L'avantage : des flux de travail décomposés (recherche → synthèse → écriture → QA) qui reflètent la façon dont les équipes réelles travaillent, mais plus rapidement, de manière évolutive et reproductible.
Démarrage rapide : Comment utiliser CrewAI en 10 minutes
Voici un modèle minimal pour vous faire passer de zéro à un équipage multi-agents fonctionnel. Nous supposerons que vous utilisez Python.
1) Installation et configuration
pip install crewai langchain-openai python-dotenv
Créez un fichier .env avec vos clés de fournisseur LLM :
OPENAI_API_KEY=sk-your-key
# ou d'autres fournisseurs pris en charge par votre stack
2) Définir vos agents (rôles + objectifs + outils)
from crewai import Agent
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0.2)
researcher = Agent(
role="Chercheur en marché",
goal="Trouver des informations crédibles et actuelles sur le marché cible et les concurrents.",
backstory=(
"Vous êtes un analyste diligent qui vérifie les affirmations, cite les sources et résume "
"les signaux provenant de publications réputées."
),
tools=[], # ajouter des outils web/search/scraper plus tard
llm=llm
)
strategist = Agent(
role="Stratège produit",
goal="Synthétiser la recherche en un positionnement clair et des options de feuille de route.",
backstory="Vous privilégiez la clarté, la faisabilité et les résultats mesurables.",
tools=[],
llm=llm
)
writer = Agent(
role="Rédacteur de contenu",
goal="Produire un brief bien structuré avec des exemples et les prochaines étapes.",
backstory="Vous écrivez dans un anglais concis et persuasif et suivez les guides de style.",
tools=[],
llm=llm
)
3) Créer des tâches (entrées, sorties et critères d'acceptation)
from crewai import Task
research_task = Task(
description=(
"Rechercher le marché américain des logiciels de gestion de projet pour PME en 2025. "
"Identifier les principaux concurrents, les niveaux de prix, les ICP et trois besoins non satisfaits. "
"Retourner des puces avec 3 à 5 citations."
),
expected_output=(
"Un brief markdown avec les sections : Taille du marché, Acteurs clés, Prix, ICP, "
"Besoins non satisfaits, Sources (avec liens)."
),
agent=researcher
)
synthesis_task = Task(
description=(
"En utilisant le brief de recherche, produire un énoncé de positionnement, 2 à 3 différenciateurs, "
"et une feuille de route de 90 jours avec des jalons."
),
expected_output="Un mémo de stratégie concis (<= 400 mots).",
agent=strategist
)
writing_task = Task(
description=(
"Transformer le mémo de stratégie en un document d'une page à destination du public. Inclure un titre, "
"une proposition de valeur, des puces de fonctionnalités et un CTA."
),
expected_output="Un document d'une page markdown adapté à une page de destination.",
agent=writer
)
4) Orchestrer l'équipage (flux + mémoire)
from crewai import Crew
crew = Crew(
agents=[researcher, strategist, writer],
tasks=[research_task, synthesis_task, writing_task],
process="sequential", # transmettre les sorties dans l'ordre
verbose=True
)
result = crew.kickoff
print(result)
Voilà votre premier pipeline fonctionnel. Vous avez défini des agents, câblé des tâches et exécuté un flux séquentiel. Pour l'étendre, ajoutez des outils (recherche, scraping, exécution de code), des étapes de validation et des étapes parallèles.
Un modèle mental pour les projets CrewAI
Pensez comme un chef de projet :
- Rôles : Qui fait quoi ? Chercheur, analyste, ingénieur, réviseur.
- Règles : Quelles normes doivent être respectées ? Guide de style, citations, tests.
- Outils : Quelles capacités sont autorisées ? Recherche Web, base de données vectorielle, Python, API.
- Tâches : Comment décomposons-nous le problème ? Entrées, sorties, critères d'acceptation.
- Transferts : Qu'est-ce qui est transmis ? Artefacts, métadonnées, contraintes.
- Commentaires : Qui valide ? Un agent d'AQ, un humain dans la boucle ou des tests.
Avec CrewAI, votre code encode ce modèle de fonctionnement.
Comment utiliser CrewAI pour un travail réel : 5 modèles éprouvés
1) Recherche → Synthèse → Rédaction (Contenu et rapports)
- Agents : Chercheur, éditeur, rédacteur, vérificateur de faits.
- Outils : Recherche Web, vérificateur de sources, guide de style.
- Conseil : Forcez les citations et un « tableau des revendications » pour éviter les hallucinations.
fact_checker = Agent(
role="Vérificateur de faits",
goal="Valider toutes les affirmations par rapport aux sources primaires ; signaler les citations faibles.",
backstory="Sceptique, méticuleux, impartial.",
llm=llm
)
qa_task = Task(
description="Valider toutes les déclarations factuelles ; ajouter des corrections en ligne avec les balises [FIX].",
expected_output="Un brouillon corrigé avec un résumé des corrections.",
agent=fact_checker
)
2) Spécification de produit à partir des tickets (Ingénierie)
- Agents : Regroupeur de tickets, auteur de spécifications, réviseur, auteur de tests.
- Outils : API de suivi des problèmes, contexte de la base de code via des incorporations, générateur de tests unitaires.
- Conseil : Ajoutez une liste de contrôle automatisée de la « Définition de terminé ».
3) Données → Aperçu → Récit (Analyse)
- Agents : Gestionnaire de données (Python), analyste, conteur.
- Outils : Pandas, SQL, création de graphiques, exécution de notebooks.
- Conseil : Utilisez un agent doté d'outils avec l'exécution
python pour des analyses vérifiables.
4) Génération de code avec garde-fous
- Agents : Planificateur, codeur, linter, testeur, réviseur.
- Outils : Lecture de dépôt, exécuteur de tests unitaires, formateur, scanner de sécurité.
- Conseil : Exigez du réviseur qu'il fasse référence aux tests qui prouvent l'exactitude.
5) Séquences d'e-mails clients à l'échelle
- Agents : Segmenteur, rédacteur, personnalisateur, QA.
- Outils : API CRM, modèles, guide de ton de marque.
- Conseil : Ajoutez un outil de vérification des rebonds/spams et forcez les variantes A/B.
Ajout d'outils : Donner aux agents de véritables capacités
CrewAI brille lorsque les agents peuvent utiliser des outils. Exemple : donnez au chercheur la recherche Web et un lecteur d'URL.
from langchain_community.tools import DuckDuckGoSearchRun
from langchain_community.document_loaders import WebBaseLoader
search = DuckDuckGoSearchRun
def web_search_tool(query: str):
return search.run(query)
def read_url_tool(url: str):
loader = WebBaseLoader(url)
docs = loader.load
return "\n\n".join([d.page_content[:2000] for d in docs])
researcher.tools = [web_search_tool, read_url_tool]
Meilleures pratiques :
- Privilège minimum : N'attachez que les outils dont l'agent a vraiment besoin.
- Discipline de schéma : Les outils doivent être déterministes et typés ; renvoyer un texte concis et structuré (JSON/Markdown) lorsque cela est possible.
- Contrôle des coûts : Gardez les sorties d'outils courtes ; résumez avant de transmettre.
Conception de tâches qui réussissent
Des tâches bien conçues font ou défont les systèmes multi-agents.
- Soyez explicite : « Renvoyez un tableau markdown avec les colonnes X, Y, Z. »
- Définissez les critères d'acceptation : « Contient 3 citations renvoyant à des sources primaires. »
- Définissez les limites : Les nombres de mots, les limites de temps ou les limites d'étapes réduisent la dérive.
- Incluez des exemples : Fournissez une mini-spécification du format de sortie souhaité.
- Ajoutez des balises de mémoire : Utilisez des titres/clés cohérents entre les tâches pour faciliter les transferts.
Exemple de squelette de tâche :
Task(
description=(
"Résumer 5 études récentes sur la productivité du travail à distance (2023-2025) avec "
"méthodologie, taille de l'échantillon et principales conclusions."
),
expected_output=(
"Markdown avec des sections H2 par étude, un tableau de comparaison final et des liens."
),
agent=researcher
)
Modes d'orchestration : Séquentiel vs. Parallèle vs. Hybride
- Séquentiel : Transferts fiables ; plus lent mais plus simple à raisonner.
- Parallèle : Plusieurs agents travaillent en même temps (par exemple, 3 chercheurs) ; fusionner plus tard.
- Hybride : Recherche en éventail en parallèle → synthèse et AQ en éventail.
Exemple hybride :
r1 = Agent(role="Chercheur A", goal="Se concentrer sur les prix", backstory="", llm=llm)
r2 = Agent(role="Chercheur B", goal="Se concentrer sur les fonctionnalités", backstory="", llm=llm)
# Tâches parallèles pour r1, r2 ; une tâche de synthèse de suivi fusionne leurs sorties.
Conseil : Lors de la fusion, demandez au synthétiseur de dédupliquer, de résoudre les conflits et de citer la source la plus solide.
Garde-fous et AQ : Gardez les agents honnêtes
- Arbitres : Ajoutez un réviseur ou un vérificateur de faits avec un pouvoir de veto explicite.
- Listes de contrôle : Encodez la conformité (confidentialité, sécurité, ton de la marque) sous forme de liste de contrôle que l'agent d'AQ doit cocher.
- Auto-critique : Demandez aux agents d'inclure une courte section « Ce que j'aurais pu manquer ».
- Déterminisme : Utilisez une température plus basse pour les agents d'AQ.
qa = Agent(
role="Réviseur d'AQ",
goal="S'assurer que les sorties répondent aux critères d'acceptation et au guide de style.",
backstory="Vous êtes strict et pédant.",
llm=llm
)
Ingénierie d'invite pour les agents CrewAI
Vos invites d'agent sont des mini-descriptions de poste. Gardez-les concises.
- Invite de rôle : Qui vous êtes, ce que vous optimisez.
- Invite d'objectif : L'état final souhaité.
- Contraintes : Nombre de mots, format, ton, références.
- Outils : Noms, quand les utiliser, ce qu'il faut renvoyer.
- Exemples : 1 à 2 échantillons courts et réalistes.
Extrait :
researcher = Agent(
role="Chercheur analytique",
goal=(
"Fournir des briefs compacts et précis avec 3 à 5 citations crédibles et une note de risque."
),
backstory=(
"Vous vérifiez les affirmations, préférez les sources primaires et signalez l'incertitude."
),
llm=llm
)
Observabilité : Voir ce que les agents ont fait (et pourquoi)
Activez les journaux détaillés et conservez les artefacts :
- Stockez l'invite, la sortie et les appels d'outils de chaque tâche.
- Enregistrez un manifeste d'exécution avec des métadonnées (modèle, température, outils).
- Conservez un bloc-notes pour les notes provisoires ; cela aide au débogage et aux audits.
Modèle :
crew = Crew(..., verbose=True, output_log_file="runs/2025-crew.log")
Conseils sur les coûts, la latence et la fiabilité
- Traitement par lots : Parallélisez les tâches indépendantes ; limitez la concurrence pour éviter les limites de débit.
- Résumer : Compressez les artefacts intermédiaires pour réduire le brassage de jetons.
- Mise en cache : Mémorisez les étapes stables (par exemple, les définitions de marché) avec des magasins de vecteurs.
- Solutions de repli : Fournissez un modèle de sauvegarde ou une politique de nouvelle tentative pour les appels instables.
- Humain dans la boucle : Insérez des portes d'approbation facultatives sur les étapes à haut risque.
Pièges courants (et comment les corriger)
- Piège : Tâches vagues → sorties sinueuses.
- Correction : Ajoutez des critères d'acceptation et des exemples explicites.
- Piège : Trop d'outils → distraction et coût.
- Correction : Privilège minimum, outils spécifiques à la tâche uniquement.
- Piège : Boucles infinies ou sur-itération.
- Correction : Ajoutez des limites d'étape/de temps et une clause « arrêter si les critères sont remplis ».
- Piège : Perte de contexte entre les agents.
- Correction : Utilisez des objets de transfert structurés (JSON) et des titres cohérents.
- Piège : Réflexion après coup sur l'AQ.
- Correction : Traitez l'AQ comme un agent de premier ordre avec un pouvoir de veto.
Exemple de bout en bout : Générateur de brief concurrentiel
Objectif : Générer un brief concurrentiel comparant trois outils pour un persona cible.
Agents :
- Analyste de persona → définit les points sensibles et les tâches à accomplir.
- Chercheur → recueille des données et des citations.
- Synthétiseur → construit un tableau de comparaison et des aperçus.
- Rédacteur → produit le brief final.
- AQ → vérifie les sources et la clarté.
Squelette :
persona = Agent(role="Analyste de persona", goal="Définir l'ICP et JTBD.", llm=llm)
researcher = Agent(role="Chercheur", goal="Recueillir des données crédibles.", llm=llm)
synth = Agent(role="Synthétiseur", goal="Comparer et interpréter.", llm=llm)
writer = Agent(role="Rédacteur", goal="Créer un brief prêt pour la direction.", llm=llm)
qa = Agent(role="AQ", goal="Valider les affirmations et la clarté.", llm=llm)
persona_task = Task(description="Définir l'ICP et JTBD pour les responsables RevOps dans SaaS.", agent=persona,
expected_output="Puces + points sensibles + mesures de réussite.")
research_task = Task(description="Recueillir les prix, les fonctionnalités et les avis pour 3 outils.", agent=researcher,
expected_output="Tableau + 5 citations.")
synth_task = Task(description="Construire une matrice de comparaison et les 3 principaux aperçus.", agent=synth,
expected_output="Tableau Markdown + aperçus.")
write_task = Task(description="Rédiger un brief d'une page avec des recommandations.", agent=writer,
expected_output="Brief exécutif en markdown.")
qa_task = Task(description="Vérifier l'exactitude et la lisibilité ; corriger les problèmes.", agent=qa,
expected_output="Brief propre et validé.")
crew = Crew(agents=[persona, researcher, synth, writer, qa],
tasks=[persona_task, research_task, synth_task, write_task, qa_task],
process="sequential", verbose=True)
print(crew.kickoff)
Quand utiliser CrewAI vs. une seule invite
Utilisez CrewAI lorsque :
- La tâche se décompose naturellement en rôles ou en étapes.
- Vous avez besoin de traçabilité, d'AQ ou d'utilisation d'outils.
- Vous construisez un pipeline réutilisable, pas une tâche ponctuelle.
Tenez-vous-en à une seule invite lorsque :
- C'est une tâche courte et subjective sans outils externes.
- La vitesse compte plus que la structure.
Au fait : Rédigez plus rapidement avec un panneau latéral IA
Si vous utilisez des flux de travail multi-agents pour rechercher, définir et rédiger du contenu, il convient de noter qu'un panneau latéral IA comme Sider.ai peut se trouver à côté de votre navigateur et de vos documents pour résumer les pages, générer des plans et affiner les brouillons en temps réel. Il ne remplacera pas l'orchestration de CrewAI, mais il peut accélérer les parties manuelles (collecte d'extraits, réécriture de sections ou vérification du ton) avant de réintégrer le contenu dans votre équipage. Prochaines étapes réalisables
- Installez CrewAI et exécutez l'exemple de démarrage rapide.
- Choisissez un flux de travail réel (recherche → brouillon → AQ) et encodez-le.
- Ajoutez un outil à la fois ; mesurez l'impact sur la qualité de la sortie et le coût.
- Introduisez un agent d'AQ avec des critères d'acceptation explicites.
- Passez à un modèle d'orchestration hybride pour la vitesse.
Principaux points à retenir
- CrewAI transforme les projets complexes en flux de travail modulaires multi-agents.
- Le succès repose sur des rôles précis, des tâches claires et une utilisation disciplinée des outils.
- Les garde-fous (AQ, listes de contrôle, limites) maintiennent les coûts bas et la qualité élevée.
- Commencez petit, puis mettez à l'échelle avec la recherche parallèle et les flux hybrides.
Mini-liste de contrôle : Comment utiliser CrewAI efficacement
- Définissez explicitement les rôles, les objectifs et les outils.
- Écrivez des tâches avec des critères d'acceptation et des exemples.
- Utilisez le séquentiel pour la fiabilité, l'hybride pour la vitesse.
- Ajoutez un agent d'AQ tôt ; donnez-lui un pouvoir de veto.
- Consignez tout ; stockez les artefacts pour les audits.
- Optimisez les coûts avec des résumés, la mise en cache et le traitement par lots.
FAQ
Q1:Qu'est-ce que CrewAI et comment l'utiliser pour des flux de travail multi-agents ?
CrewAI est un framework pour orchestrer plusieurs agents d'IA avec des rôles, des tâches et des outils. Vous l'utilisez en définissant des agents, en créant des tâches avec des critères d'acceptation et en exécutant un équipage qui coordonne les transferts pour produire une sortie finale.
Q2 : Comment ajouter des outils comme la recherche web aux agents CrewAI ?
Attachez des fonctions d'outil à un agent et indiquez quand les utiliser. Gardez les sorties structurées et courtes (par exemple, JSON ou markdown) pour contrôler les coûts et améliorer les transferts.
Q3 : Quand devrais-je utiliser CrewAI au lieu d'une simple invite LLM ?
Utilisez CrewAI lorsqu'une tâche se décompose en étapes, nécessite l'utilisation d'outils ou d'assurance qualité, ou a besoin de pipelines reproductibles. Utilisez une simple invite pour les tâches rapides et subjectives qui n'ont pas besoin de structure.
Q4 : Comment puis-je empêcher les hallucinations dans les sorties CrewAI ?
Ajoutez un agent de vérification des faits ou d'assurance qualité avec droit de veto, exigez des citations de sources primaires, définissez une température basse pour l'assurance qualité et spécifiez des critères d'acceptation comme un tableau de revendications.
Q5 : CrewAI peut-il exécuter des tâches en parallèle pour accélérer les choses ?
Oui. Utilisez des agents parallèles pour les tâches indépendantes (par exemple, plusieurs chercheurs), puis une tâche de synthèse pour fusionner les résultats. L'orchestration hybride équilibre la vitesse et la fiabilité.