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

> Découvrez CrewAI pas à pas : installation, agents et tâches en YAML, orchestration en Python, outils, CrewAI Studio et erreurs à éviter.

- URL : https://guides-numeriques.fr/ia/crewai/
- Thématique : IA générative & agents
- Mis à jour : 2026-09-26
- Formation associée : [Cours pour apprendre CrewAI : créer des agents IA autonomes - guide complet](https://espritacademique.com/formations/cours-pour-apprendre-crewai-creer-des-agents-ia-autonomes-guide-complet/)

## L'essentiel

- CrewAI est un framework Python open source qui fait collaborer plusieurs agents IA, chacun doté d'un rôle, d'un objectif et d'outils, pour accomplir une mission commune.
- Un projet CrewAI repose sur trois notions : les agents (qui travaillent), les tâches (ce qu'il faut produire) et la crew (l'équipe qui orchestre le tout).
- La commande crewai create crew génère un projet prêt à l'emploi, avec les agents décrits dans agents.yaml et les tâches dans tasks.yaml.
- Le processus séquentiel exécute les tâches dans l'ordre ; le processus hiérarchique confie la répartition du travail à un agent manager.
- CrewAI Studio, sur la plateforme cloud de l'éditeur, permet de construire et modifier des équipes d'agents dans un éditeur visuel, sans écrire de code.

**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](https://guides-numeriques.fr/ia/creer-agent-ia/), 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](https://guides-numeriques.fr/developpement/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 :

```bash
# 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.


**Schéma — Créer une crew avec CrewAI en 6 étapes**

1. **Générer le projet** : crewai create crew crée l'arborescence
2. **Définir les agents** : role, goal et backstory dans agents.yaml
3. **Définir les tâches** : Un expected_output précis dans tasks.yaml
4. **Assembler la crew** : Agents, tâches et outils reliés dans crew.py
5. **Lancer l'exécution** : Variables dans main.py, puis crewai run
6. **Évaluer et itérer** : Une seule modification à la fois


### Étape 1 — Comprendre la structure du projet

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

```text
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.

```yaml
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

```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 :

```python
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 :

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

Puis, depuis la racine du projet :

```bash
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.

> **Formation recommandée** : [Cours pour apprendre CrewAI : créer des agents IA autonomes - guide complet](https://espritacademique.com/formations/cours-pour-apprendre-crewai-creer-des-agents-ia-autonomes-guide-complet/) — 1h45 de vidéo, 44 €.

## 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.


**Schéma — CrewAI : processus séquentiel ou hiérarchique ?**

| Process.sequential | Process.hierarchical |
|---|---|
| Tâches dans l'ordre déclaré | Un agent manager répartit et valide |
| Prévisibilité élevée | Résultats plus variables |
| Coût en appels au modèle faible | Coût plus élevé |
| Aucune configuration | manager_llm ou manager_agent requis |
| Chaînes claires : chercher, rédiger | Missions ouvertes |


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 :

```python
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](https://guides-numeriques.fr/data/web-scraping-python-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 :

```python
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](https://guides-numeriques.fr/ia/rag-langchain-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](https://guides-numeriques.fr/automatisation/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](https://guides-numeriques.fr/ia/cursor-ia/) 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](https://espritacademique.com/formations/cours-pour-apprendre-crewai-creer-des-agents-ia-autonomes-guide-complet/) 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.

## Sources et documentation officielle

- [Installation (Documentation CrewAI)](https://docs.crewai.com/en/installation)
- [Agents (Documentation CrewAI)](https://docs.crewai.com/en/concepts/agents)
- [Tasks (Documentation CrewAI)](https://docs.crewai.com/en/concepts/tasks)
- [Processes (Documentation CrewAI)](https://docs.crewai.com/en/concepts/processes)

## Questions fréquentes

### CrewAI est-il gratuit ?

Le framework CrewAI est open source et gratuit : vous pouvez l'installer et l'utiliser sans licence. En revanche, les modèles de langage appelés par vos agents sont souvent payants à l'usage si vous passez par une API. La plateforme cloud (CrewAI Enterprise et CrewAI Studio) propose ses propres formules : consultez la page tarifs officielle pour connaître les conditions actuelles.

### Faut-il savoir coder en Python pour utiliser CrewAI ?

Pour le framework, des bases de Python suffisent : l'essentiel de la configuration se fait dans des fichiers YAML lisibles, et le code généré est court. Savoir lancer une commande dans un terminal et créer un environnement virtuel est indispensable. Pour un usage entièrement visuel, CrewAI Studio permet de construire des équipes d'agents sans coder.

### Quelle différence entre CrewAI et LangChain ?

LangChain est une bibliothèque de composants pour construire des applications à base de LLM : chaînes, connecteurs, RAG. CrewAI est spécialisé dans l'orchestration de plusieurs agents qui jouent des rôles et se passent des tâches. Les deux se complètent : on peut utiliser des outils ou des modèles de l'écosystème LangChain à l'intérieur d'une équipe CrewAI.

### Peut-on utiliser CrewAI avec un modèle local comme Llama ou Mistral ?

Oui. CrewAI peut s'appuyer sur un modèle servi localement par Ollama. Il suffit d'indiquer le modèle au format ollama/nom-du-modele et l'adresse du serveur local dans la configuration. Les petits modèles locaux gèrent toutefois moins bien les enchaînements d'outils que les grands modèles accessibles par API : testez sur des tâches simples.

### Combien d'agents faut-il dans une crew ?

Deux à quatre agents suffisent dans la grande majorité des cas. Chaque agent supplémentaire ajoute des appels au modèle, donc du temps et du coût, ainsi que des risques d'incompréhension. Commencez avec le minimum, par exemple un chercheur et un rédacteur, et n'ajoutez un agent que si une étape a vraiment besoin d'un rôle et d'outils distincts.

### Combien de temps pour apprendre CrewAI ?

Deux heures de pratique guidée suffisent pour installer l'environnement, créer un projet, configurer des agents et des tâches, puis lancer une première équipe. Comptez ensuite quelques jours de projets personnels pour maîtriser les outils, le processus hiérarchique, la mémoire et les modèles locaux.