CrewAI : programmer une équipe d'agents IA autonomes en Python, pas à pas

CrewAI est un framework Python open source qui permet de créer une équipe d’agents IA autonomes : chaque agent reçoit un rôle, un objectif et des outils, puis les agents se répartissent des tâches pour produire un résultat commun, comme un rapport de veille, une analyse de marché ou un article relu et corrigé.

Ce tutoriel s’adresse aux développeurs, freelances et entrepreneurs qui ont déjà utilisé ChatGPT et veulent aller plus loin en automatisant des processus en plusieurs étapes. Vous verrez comment installer CrewAI, générer la structure d’un projet, écrire vos agents et vos tâches, lancer l’équipe, puis retrouver la même logique dans l’éditeur visuel CrewAI Studio.

Si vous cherchez d’abord une vue d’ensemble des outils pour bâtir des agents (n8n, LangChain, Ollama…), commencez par notre guide pour créer un agent IA de A à Z, puis revenez ici pour la partie multi-agents.

Qu’est-ce que CrewAI ?

CrewAI est une bibliothèque Python d’orchestration multi-agents. Elle organise le travail de plusieurs agents IA à la manière d’une équipe humaine : chaque membre a une spécialité, reçoit des tâches précises et transmet son travail au suivant. Le framework gère les appels au modèle de langage, les outils et l’enchaînement des étapes.

Trois notions structurent tout projet :

• Agent : un membre de l’équipe défini par un rôle (role), un objectif (goal), un contexte (backstory), un modèle de langage et éventuellement des outils.
• Task : une tâche précise, avec une description, le résultat attendu (expected_output) et l’agent qui en est responsable.
• Crew : l’équipe qui rassemble agents et tâches et définit le processus d’exécution.

À côté des crews, CrewAI propose les Flows, qui servent à enchaîner des étapes de façon plus déterministe (code classique, conditions, appels de crews) quand vous avez besoin de contrôler précisément le déroulement.

Pourquoi utiliser une équipe d’agents IA plutôt qu’un seul agent ?

Un agent unique chargé de chercher, analyser, rédiger et vérifier reçoit un prompt long et contradictoire. Découper le travail entre agents spécialisés apporte plusieurs bénéfices :

• Des instructions plus courtes et plus précises : chaque agent n’a qu’un métier à exercer.
• Des outils ciblés : seul l’agent chercheur a accès à la recherche web, seul l’agent analyste lit les fichiers.
• Un contrôle qualité intégré : un agent relecteur vérifie le travail des autres avant la sortie finale.
• Un choix de modèle par agent : un modèle puissant pour l’analyse, un modèle plus léger et moins coûteux pour la mise en forme.
• Une maintenance simplifiée : on améliore un agent sans toucher aux autres.

Les cas d’usage typiques, avec la répartition des rôles qui fonctionne bien en pratique :

• Veille concurrentielle : un chercheur collecte les nouveautés, un analyste en tire trois enseignements, un rédacteur met en forme la note.
• Préparation de rendez-vous commerciaux : un agent rassemble les informations publiques sur l’entreprise cliente, un second prépare les questions et les arguments adaptés.
• Rédaction de contenus : un agent établit le plan à partir des sources, un rédacteur écrit, un relecteur vérifie la cohérence et signale les affirmations non sourcées.
• Analyse de documents : un agent extrait les données d’une série de fichiers, un autre les compare et produit un tableau de synthèse.
• Rapports récurrents : une équipe relancée chaque semaine avec de nouvelles variables d’entrée produit le même livrable, au même format.

Installer CrewAI avec Python et VS Code

Avant de coder, il vous faut un environnement propre. Si Python est nouveau pour vous, notre guide pour apprendre Python couvre les bases utiles (variables, fonctions, modules).

Prérequis

• Python dans une version récente prise en charge par CrewAI (vérifiez la plage indiquée dans la documentation officielle, elle évolue avec les versions du framework).
• Visual Studio Code avec l’extension Python.
• Une clé d’API d’un fournisseur de modèles (OpenAI, Anthropic, Google, Mistral…), ou Ollama installé si vous préférez un modèle local.

Installation

CrewAI s’appuie sur uv, un gestionnaire de paquets Python rapide. Une fois uv installé, ouvrez un terminal dans VS Code :

# Installer l'outil en ligne de commande CrewAI
uv tool install crewai

# Vérifier l'installation
crewai --version

# Créer un nouveau projet d'équipe
crewai create crew veille_marche

L’assistant vous demande alors le fournisseur de modèle, le modèle à utiliser et votre clé d’API. Ces informations sont enregistrées dans le fichier .env du projet.

Comment créer une crew avec CrewAI : les étapes

Prenons un exemple concret : une équipe de deux agents qui produit une note de veille sur un marché donné. Un chercheur collecte les informations, un analyste rédige la synthèse.

Étape 1 — Comprendre la structure du projet

La commande crewai create crew génère cette arborescence :

veille_marche/
├── .env                  # clés d'API et choix du modèle
├── pyproject.toml        # dépendances du projet
├── knowledge/            # documents de référence (optionnel)
└── src/veille_marche/
    ├── main.py           # point d'entrée, variables d'entrée
    ├── crew.py           # assemblage des agents et des tâches
    ├── tools/
    │   └── custom_tool.py
    └── config/
        ├── agents.yaml   # définition des agents
        └── tasks.yaml    # définition des tâches

Cette séparation est la grande force de la version actuelle de CrewAI : le comportement se décrit en YAML, le code Python se contente d’assembler. Vous pouvez donc améliorer un agent sans toucher au code.

Étape 2 — Définir les agents dans agents.yaml

Chaque agent se décrit par trois champs. Les accolades désignent des variables remplacées au lancement.

chercheur:
  role: >
    Analyste de veille sur le marché {marche}
  goal: >
    Identifier les tendances, acteurs et nouveautés récentes
    du marché {marche}, avec leurs sources
  backstory: >
    Vous êtes un analyste rigoureux. Vous ne retenez que des
    informations vérifiables et vous citez toujours la source.

analyste:
  role: >
    Rédacteur de notes stratégiques
  goal: >
    Transformer les informations collectées en une note claire
    et actionnable pour un dirigeant
  backstory: >
    Vous rédigez des synthèses courtes, structurées, sans jargon,
    et vous signalez explicitement les points incertains.

Le champ backstory n’est pas décoratif : il fixe le niveau d’exigence et le ton. Un bon goal est mesurable et un bon role est spécifique.

Étape 3 — Définir et assigner les tâches dans tasks.yaml

recherche_task:
  description: >
    Recherchez les informations récentes sur le marché {marche} :
    principaux acteurs, lancements, évolutions réglementaires.
  expected_output: >
    Une liste de 8 à 12 points factuels, chacun avec sa source.
  agent: chercheur

synthese_task:
  description: >
    À partir de la recherche, rédigez une note de veille destinée
    à un dirigeant : contexte, trois tendances, risques, recommandations.
  expected_output: >
    Une note en Markdown d'une page maximum, avec des titres.
  agent: analyste

Le champ expected_output est le plus important : c’est lui qui indique à l’agent quand son travail est terminé et sous quelle forme le rendre. En formation, la majorité des résultats décevants viennent d’un expected_output trop vague.

Étape 4 — Assembler l’équipe dans crew.py

Le fichier généré relie les définitions YAML aux objets Python grâce à des décorateurs :

from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task
from crewai_tools import SerperDevTool

@CrewBase
class VeilleMarche():
    """Équipe de veille : un chercheur et un analyste"""

    @agent
    def chercheur(self) -> Agent:
        return Agent(
            config=self.agents_config['chercheur'],
            tools=[SerperDevTool()],   # recherche web (clé SERPER_API_KEY)
            verbose=True
        )

    @agent
    def analyste(self) -> Agent:
        return Agent(config=self.agents_config['analyste'], verbose=True)

    @task
    def recherche_task(self) -> Task:
        return Task(config=self.tasks_config['recherche_task'])

    @task
    def synthese_task(self) -> Task:
        return Task(
            config=self.tasks_config['synthese_task'],
            output_file='note_veille.md'
        )

    @crew
    def crew(self) -> Crew:
        return Crew(
            agents=self.agents,
            tasks=self.tasks,
            process=Process.sequential,
            verbose=True
        )

Seul le chercheur reçoit l’outil de recherche : c’est un bon réflexe de n’attribuer à chaque agent que les outils dont il a besoin.

Étape 5 — Passer les variables et lancer l’exécution

Dans main.py, la fonction run() transmet les valeurs des variables :

def run():
    inputs = {'marche': 'les vélos électriques en France'}
    VeilleMarche().crew().kickoff(inputs=inputs)

Puis, depuis la racine du projet :

crewai install   # installe les dépendances du projet
crewai run       # lance l'équipe

Avec verbose=True, le terminal affiche le raisonnement de chaque agent, les outils appelés et les résultats intermédiaires. Lisez-les attentivement lors des premiers essais : c’est là que vous repérez un agent qui tourne en rond ou une tâche mal formulée. Le résultat final est écrit dans note_veille.md.

Étape 6 — Évaluer le résultat et itérer

Une première exécution donne rarement le résultat idéal. Adoptez une démarche d’amélioration méthodique plutôt que de tout réécrire à chaque essai :

1. Relisez la sortie finale avec un critère simple : le document répond-il à la demande, dans le format demandé, sans information inventée ?
2. Remontez à la tâche fautive : si la synthèse est pauvre, vérifiez d’abord ce que le chercheur lui a transmis. Un rédacteur ne peut pas compenser une recherche insuffisante.
3. Modifiez une seule chose à la fois : un expected_output plus précis, un backstory plus exigeant, un outil supplémentaire. Relancez, comparez.
4. Changez de variables d’entrée : testez l’équipe sur trois ou quatre marchés différents pour vérifier que le comportement reste stable.

Notez vos modifications et leurs effets dans un fichier à part. Au bout de quelques itérations, vous obtenez une équipe dont le comportement est prévisible, ce qui est la condition pour l’utiliser régulièrement ou la confier à d’autres personnes.

Processus séquentiel ou hiérarchique : bien orchestrer les agents et tâches

Le paramètre process de la crew détermine qui décide de l’ordre du travail.

Critère	Process.sequential	Process.hierarchical
Fonctionnement	Les tâches s’exécutent dans l’ordre déclaré	Un agent manager répartit et valide les tâches
Prévisibilité	Élevée	Plus variable
Coût en appels au modèle	Faible	Plus élevé (le manager raisonne aussi)
Configuration	Aucune	Nécessite un manager_llm ou un manager_agent
Idéal pour	Chaînes claires : chercher, analyser, rédiger	Missions ouvertes où l’ordre dépend des résultats

Notre conseil : restez en séquentiel tant que vous le pouvez. Le mode hiérarchique est séduisant, mais il rend les résultats moins reproductibles et plus difficiles à déboguer.

Deux options complètent l’orchestration. Le paramètre context d’une tâche permet de lui transmettre explicitement le résultat d’une ou plusieurs tâches précédentes. Et human_input=True met l’exécution en pause pour vous demander une validation avant de poursuivre.

Outils, mémoire et modèles : les réglages qui comptent

Ajouter des outils

Le paquet crewai_tools fournit des outils prêts à l’emploi : recherche web, lecture de sites, lecture de fichiers, recherche dans des PDF… Vous pouvez aussi créer les vôtres dans tools/custom_tool.py en décrivant précisément ce que fait l’outil : l’agent choisit l’outil en lisant cette description. Le décorateur @tool offre la syntaxe la plus courte :

from crewai.tools import tool

@tool("Compter les mots")
def compter_mots(texte: str) -> str:
    """Compte le nombre de mots d'un texte. À utiliser pour vérifier
    qu'une note respecte la longueur demandée."""
    return f"{len(texte.split())} mots"

La docstring sert de mode d’emploi à l’agent : indiquez ce que fait l’outil et dans quelle situation l’utiliser. Un outil qui renvoie une erreur explicite (« fichier introuvable », « aucune donnée pour cette date ») aide aussi l’agent à corriger sa démarche au lieu d’inventer une réponse. Pour de la collecte de données plus poussée, les techniques de web scraping avec Python et pandas se combinent très bien avec un outil personnalisé.

Activer la mémoire

Le paramètre memory=True sur la crew active la mémoire intégrée : les agents conservent des éléments des exécutions précédentes. Utile pour des tâches récurrentes, à surveiller pour la confidentialité.

Choisir le modèle de chaque agent

Chaque agent peut utiliser un modèle différent via le paramètre llm. Pour un modèle local servi par Ollama, la configuration ressemble à ceci :

from crewai import LLM

llm_local = LLM(model="ollama/mistral", base_url="http://localhost:11434")

Les grands modèles accessibles par API restent plus fiables pour l’usage d’outils ; les modèles locaux conviennent bien aux tâches de rédaction ou de reformulation. Pour des agents qui répondent à partir de vos propres documents, voyez notre tutoriel RAG avec LangChain et Ollama.

CrewAI Studio et CrewAI Enterprise : la version visuelle

CrewAI ne se limite pas au code. L’éditeur propose une plateforme cloud, présentée sous le nom CrewAI Enterprise, qui sert à déployer, surveiller et partager des équipes d’agents. On y retrouve CrewAI Studio, un éditeur visuel dans lequel vous décrivez votre besoin, ajoutez des agents et des tâches, et reliez des outils ou des applications sans écrire de Python.

Le Studio est pratique pour prototyper rapidement ou faire travailler des profils non développeurs sur les agents. Le code reste préférable pour versionner les projets, les tester finement et les héberger où vous le souhaitez. L’offre et l’interface de la plateforme évoluant vite, vérifiez les fonctionnalités disponibles directement sur le site officiel de CrewAI.

Si votre entreprise travaille dans l’écosystème Microsoft, Copilot Studio est l’équivalent le plus proche côté outils sans code, avec une intégration native à Teams et à Microsoft 365.

Les erreurs fréquentes avec CrewAI

Erreur	Symptôme	Solution
expected_output vague	Résultat trop long, hors format ou incomplet	Préciser format, longueur et structure attendus
Trop d’agents	Exécution lente et coûteuse, résultats dilués	Commencer à deux ou trois agents
Tous les outils donnés à tous les agents	Appels d’outils inutiles, boucles	Attribuer les outils agent par agent
Variables non transmises	Accolades {marche} restées telles quelles	Vérifier les clés du dictionnaire inputs
Clé d’API absente du .env	Erreur d’authentification au lancement	Contrôler le fichier .env et le nom des variables
Version de Python non prise en charge	Échec de l’installation	Utiliser une version compatible dans un environnement dédié
Mode hiérarchique par défaut	Résultats instables d’une exécution à l’autre	Revenir au séquentiel, puis ajouter du contrôle
Petit modèle local pour tout	Outils mal utilisés, raisonnement confus	Réserver les modèles locaux aux tâches simples

Un réflexe utile : ajoutez output_file à chaque tâche pendant la mise au point. Vous pourrez relire le résultat intermédiaire de chaque agent et identifier précisément où la qualité se dégrade.

Comment apprendre CrewAI rapidement ?

CrewAI s’apprend vite quand on suit une progression concrète :

1. Environnement : installer Python, VS Code, uv et CrewAI, puis générer un premier projet.
2. Premier projet : lire la structure générée, modifier les agents et les tâches du modèle fourni, lancer l’exécution.
3. Projet personnel : construire une équipe de deux ou trois agents sur un cas réel (veille, préparation de rendez-vous, rédaction).
4. Approfondissement : outils personnalisés, mémoire, processus hiérarchique, modèles locaux.
5. Version visuelle : reproduire votre équipe dans CrewAI Studio pour comparer les deux approches.

Pour écrire et déboguer votre code plus vite, un éditeur assisté par l’IA comme Cursor aide beaucoup à comprendre les messages d’erreur et à générer les outils personnalisés.

Si vous préférez être guidé, le cours vidéo pour apprendre CrewAI d’EspritAcadémique suit exactement ce chemin en 1 h 45, sans prérequis. Au programme :

• les concepts des agents IA autonomes et l’installation de Python, VS Code et CrewAI ;
• la génération d’un projet et la lecture de sa nouvelle architecture de fichiers ;
• la configuration des agents, puis la définition et l’attribution des tâches ;
• l’exécution et le test d’une équipe complète ;
• la découverte de CrewAI Enterprise et la prise en main de l’éditeur visuel CrewAI Studio.

En résumé

CrewAI organise des agents IA comme une équipe : des rôles clairs dans agents.yaml, des tâches précises dans tasks.yaml, un assemblage court dans crew.py, puis crewai run. Soignez les expected_output, limitez le nombre d’agents et d’outils, restez en processus séquentiel au début et relisez les sorties intermédiaires. Le Studio offre ensuite une alternative visuelle pour prototyper sans code.