CrewAI : orchestre ton armée d'agents IA

Tu as déjà utilisé ChatGPT pour répondre à une question. Maintenant imagine une équipe entière d'IA spécialisées — un chercheur, un rédacteur, un relecteur — qui bossent ensemble sur une tâche complexe, sans que tu aies à les micro-manager. C'est exactement ce que permet CrewAI, le framework multi-agents qui explose en 2026 (50 000+ étoiles GitHub). Dans ce tutoriel, tu vas construire ta première crew d'agents IA, compatible avec la version 1.15.9 (juillet 2026).

Le problème que CrewAI résout

Un LLM seul, c'est comme un employé ultra-polyvalent mais sans spécialité. Il fait tout, moyennement bien. Dès que ta tâche devient complexe — par exemple « fais une recherche sur les dernières avancées en IA, rédige un article de 1000 mots, puis relis-le pour corriger les fautes » — un seul appel à ChatGPT ne suffit pas.

Tu pourrais enchaîner plusieurs prompts à la main. Mais c'est fastidieux, et tu perds le contexte entre chaque étape.

CrewAI résout ça avec un concept simple : tu définis des agents spécialisés avec des rôles, des objectifs et des outils, puis tu les fais collaborer sur une tâche commune. Chaque agent a un backstory (son « CV »), des compétences, et peut utiliser des outils comme la recherche web ou l'exécution de code.

Comment fonctionne CrewAI (v1.15.9)

Le framework repose sur quatre briques principales :

Agent — un « employé IA » avec un rôle, un objectif et une personnalité. Depuis la v1.x, il supporte le reasoning (reasoning=True), les skills (instructions markdown injectées dans le prompt), et la knowledge (RAG sur documents).
Task — une mission confiée à un agent, avec un résultat attendu. Les tâches supportent le structured output (output_pydantic, output_json, output_file), les callbacks, et le context pour chaîner les sorties.
Crew — l'orchestrateur qui lance les agents dans le bon ordre (sequential ou hierarchical). Supporte le memory, le planning automatique, le streaming et les checkpoints.
Flow — (nouveau en v1.x) un pipeline événementiel avec décorateurs @start() et @listen(), état typé via Pydantic, et persistance. Recommandé pour les apps de production.

Ce qui a changé depuis la v0.80

Si tu as un vieux projet CrewAI, voici les breaking changes majeurs :

Installation : on utilise uv au lieu de pip+venv. uv tool install crewai pour le CLI, crewai create crew pour les projets.
Configuration LLM : format "provider/model-id" (ex: "openai/gpt-4o", "anthropic/claude-sonnet-4-6") via LiteLLM. La classe LLM() remplace les vieilles variables d'environnement OPENAI_API_BASE.
Projets JSON-first : les agents se définissent dans agents/*.jsonc, les tâches dans crew.jsonc. L'ancien format crew.py + config/*.yaml est dispo avec --classic.
`CodeInterpreterTool` retiré : allow_code_execution et code_execution_mode sont dépréciés. Utilise E2B ou Modal pour du sandbox.
`crewai-tools` n'est plus obligatoire : installe-le séparément avec crewai[tools] si tu utilises SerperDevTool, FileReadTool, etc.
`allow_delegation` : toujours présent, mais default=False (était True avant).
`memory` : désactivé par défaut (False). À activer explicitement.
`max_iter` : défaut passé à 20 (était plus bas avant).
Imports : from crewai.tools import BaseTool, tool (plus from crewai_tools import BaseTool).
Flows : nouvelle API avec @start(), @listen(), état Pydantic. Remplacer l'ancien chaînage manuel.

Installation : prépare ton environnement

CrewAI v1.15.9 utilise uv comme gestionnaire de dépendances. Python 3.10 à 3.13 requis.

bash

# 1. Installer uv (si pas déjà fait)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Installer le CLI CrewAI global
uv tool install crewai

# 3. Vérifier
crewai --version
# → crewai 1.15.9

Pour créer un projet :

bash

# Créer un nouveau projet (format JSON-first)
crewai create crew ma-crew-ia
cd ma-crew-ia

# Installer les dépendances
crewai install

Ton projet aura cette structure :

text

ma-crew-ia/
├── .env              # API keys
├── agents/           # Un fichier .jsonc par agent
│   └── researcher.jsonc
├── crew.jsonc        # Configuration de la crew + tâches
├── knowledge/        # Documents pour RAG
├── skills/           # Instructions markdown
├── tools/            # Outils custom (custom:<name>)
└── pyproject.toml

Pour l'ancien format (crew.py + YAML), utilise crewai create crew ma-crew-ia --classic.

Ton premier agent (v1.15.9)

Avant d'orchestrer une équipe, crée un seul agent en Python pur :

python

# mon_premier_agent.py
from crewai import Agent, Task, Crew

# 1. Définir l'agent (API v1.x)
assistant = Agent(
    role="Assistant Personnel",
    goal="Aider l'utilisateur avec des réponses claires et utiles",
    backstory=(
        "Tu es un assistant IA bienveillant, formé à la vulgarisation scientifique. "
        "Tu expliques les choses simplement, sans jargon inutile."
    ),
    llm="openai/gpt-4o",  # Format provider/model-id
    verbose=True,
)

# 2. Définir la tâche
tache = Task(
    description=(
        "Explique en 3 phrases simples ce qu'est un agent IA "
        "à quelqu'un qui n'y connaît rien en informatique."
    ),
    expected_output="Une explication en 3 phrases simples, en français.",
    agent=assistant
)

# 3. Créer la crew et lancer
crew = Crew(
    agents=[assistant],
    tasks=[tache],
    verbose=True
)

resultat = crew.kickoff()
print("\n=== RÉSULTAT FINAL ===")
print(resultat.raw)  # .raw pour le texte brut

Lance le script :

bash

# Définir ta clé API OpenAI
export OPENAI_API_KEY="sk-..."

python3 mon_premier_agent.py

Brancher un LLM gratuit : Ollama en local

Avec CrewAI v1.x, tu peux utiliser Ollama via LiteLLM :

bash

# Installer Ollama
curl -fsSL https://ollama.com/install.sh | sh
ollama pull llama3.2:3b

Puis dans ton .env ou ton code :

python

from crewai import Agent, LLM

# Option 1 : via variable d'environnement
# Dans .env : MODEL=ollama/llama3.2:3b

# Option 2 : via LLM explicite
llm = LLM(
    model="ollama/llama3.2:3b",
    base_url="http://localhost:11434",
)

agent = Agent(
    role="Assistant Local",
    goal="Répondre aux questions en français",
    backstory="Assistant léger tournant en local via Ollama.",
    llm=llm,
    verbose=True,
)

Pour utiliser Anthropic, Google, ou autre provider natif :

bash

# Anthropic
uv add "crewai[anthropic]"
# Dans .env : ANTHROPIC_API_KEY=sk-ant-...
# Dans le code : llm="anthropic/claude-sonnet-4-6"

# Google Gemini
uv add "crewai[gemini]"
# llm="gemini/gemini-2.0-flash-001"

Le vrai projet : une équipe de journalistes IA

Tu vas créer trois agents qui collaborent pour produire un article d'actualité :

Agent	Rôle	Outil
Chercheur	Trouver les infos récentes	Recherche web (SerperDevTool)
Rédacteur	Rédiger l'article	—
Relecteur	Corriger et améliorer	—

Étape 1 : installer les dépendances

bash

# Dans ton projet CrewAI
uv add "crewai[tools]"

Étape 2 : les outils

python

# equipe_journalistes.py
import os
from crewai import Agent, Task, Crew, Process
from crewai_tools import SerperDevTool, ScrapeWebsiteTool

# Clé API Serper (gratuit, 2500 requêtes/mois sur serper.dev)
os.environ["SERPER_API_KEY"] = "ta-clé-serper-ici"

# Outils
outil_recherche = SerperDevTool()
outil_scraping = ScrapeWebsiteTool()

Étape 3 : les agents

python

# Agent 1 : le Chercheur
chercheur = Agent(
    role="Chercheur Web Senior",
    goal=(
        "Trouver les informations les plus récentes et pertinentes "
        "sur le sujet demandé. Tu dois citer tes sources."
    ),
    backstory=(
        "Ancien journaliste d'investigation reconverti dans la veille tech. "
        "Tu as un don pour dénicher l'info que personne d'autre ne trouve. "
        "Tu ne te contentes jamais du premier résultat Google."
    ),
    tools=[outil_recherche, outil_scraping],
    llm="openai/gpt-4o",
    verbose=True,
)

# Agent 2 : le Rédacteur
redacteur = Agent(
    role="Rédacteur Tech",
    goal=(
        "Rédiger un article clair, engageant et bien structuré "
        "à partir des recherches fournies par le Chercheur."
    ),
    backstory=(
        "Plume affûtée de la rédaction tech. Tu sais transformer "
        "des notes de recherche brutes en contenu captivant. "
        "Ton style est direct, sans langue de bois, avec une pointe d'humour. "
        "Tu écris toujours en français."
    ),
    llm="openai/gpt-4o",
    verbose=True,
)

# Agent 3 : le Relecteur
relecteur = Agent(
    role="Relecteur-Correcteur",
    goal=(
        "Relire l'article rédigé, corriger les fautes d'orthographe, "
        "de grammaire et améliorer la fluidité. Vérifier la cohérence."
    ),
    backstory=(
        "Correcteur professionnel avec 20 ans d'expérience dans la presse. "
        "Aucune coquille ne t'échappe. Tu es intraitable sur la grammaire "
        "mais respectueux du style de l'auteur."
    ),
    llm="openai/gpt-4o-mini",  # Modèle moins cher pour la relecture
    verbose=True,
)

Étape 4 : les tâches (le séquencement)

python

# Tâche 1 : Recherche
tache_recherche = Task(
    description=(
        "Recherche les 3 actualités les plus importantes en intelligence "
        "artificielle de cette semaine. Pour chaque actualité, "
        "trouve une source fiable, résume le sujet en 2-3 phrases, et note l'URL."
    ),
    expected_output=(
        "Un rapport de recherche structuré avec 3 actualités. "
        "Pour chacune : titre, résumé 2-3 phrases, source (URL). "
        "Format : markdown."
    ),
    agent=chercheur
)

# Tâche 2 : Rédaction (dépend de la recherche)
tache_redaction = Task(
    description=(
        "À partir du rapport de recherche fourni, rédige un article "
        "de 400-500 mots en français. Structure :"
        "\n1. Un titre accrocheur"
        "\n2. Une introduction qui donne le contexte"
        "\n3. Une section par actualité"
        "\n4. Une conclusion qui fait le lien entre les 3 actus"
    ),
    expected_output="Un article complet en markdown, 400-500 mots, en français.",
    agent=redacteur,
    context=[tache_recherche]  # La sortie du chercheur devient l'entrée du rédacteur
)

# Tâche 3 : Relecture (dépend de la rédaction)
tache_relecture = Task(
    description=(
        "Relis l'article fourni. Corrige TOUTES les fautes d'orthographe "
        "et de grammaire. Améliore les tournures maladroites. "
        "Vérifie que tous les liens et URLs sont corrects. "
        "Retourne l'article corrigé EN ENTIER."
    ),
    expected_output="L'article intégralement relu et corrigé, en markdown.",
    agent=relecteur,
    context=[tache_redaction],  # La sortie du rédacteur devient l'entrée du relecteur
    output_file="output/article_final.md",  # Sauvegarde automatique
)

Étape 5 : le lancement

python

# Assemblage et décollage
equipe = Crew(
    agents=[chercheur, redacteur, relecteur],
    tasks=[tache_recherche, tache_redaction, tache_relecture],
    process=Process.sequential,  # Exécution en séquence
    verbose=True
)

print("\n🚀 LANCEMENT DE LA CREW JOURNALISTE\n")
article_final = equipe.kickoff()

# Résultat
print("\n" + "="*60)
print("  ARTICLE FINAL (relu et corrigé)")
print("="*60)
print(article_final.raw)

# Métriques d'usage (tokens consommés)
if hasattr(article_final, 'usage_metrics'):
    print(f"\n📊 Tokens utilisés : {article_final.usage_metrics}")

Le script complet fait moins de 120 lignes. Lance-le :

bash

python3 equipe_journalistes.py

Tu vas voir CrewAI enchaîner les trois agents automatiquement. Le Relecteur ne démarre que quand le Rédacteur a fini, qui ne démarre que quand le Chercheur a fini. Zéro orchestration manuelle.

Ce que tu viens d'accomplir

En 30 minutes, tu as :

Installé CrewAI v1.15.9 avec uv
Créé ton premier agent avec l'API actuelle (llm="openai/gpt-4o")
Branché Ollama pour du LLM local gratuit
Construit une équipe multi-agents avec chaînage via context=[tache_précédente]
Produit un article complet avec recherche web, rédaction et relecture

Aller plus loin avec les Flows

Depuis la v1.x, CrewAI recommande les Flows pour les applications de production. Un Flow te donne :

Un état typé avec Pydantic
Des étapes chaînées avec @start() et @listen()
La persistance et la reprise sur erreur

Voici un Flow minimal qui lance ta crew de journalistes :

python

# flow_journalistes.py
from pydantic import BaseModel
from crewai.flow import Flow, listen, start
from equipe_journalistes import equipe  # ta crew définie plus haut

class JournalisteState(BaseModel):
    sujet: str = ""
    article: str = ""

class FlowJournaliste(Flow[JournalisteState]):

    @start()
    def definir_sujet(self):
        self.state.sujet = "Avancées en IA - Juillet 2026"

    @listen(definir_sujet)
    def lancer_crew(self):
        resultat = equipe.kickoff()
        self.state.article = resultat.raw

    @listen(lancer_crew)
    def resume(self):
        print(f"Article généré : {len(self.state.article)} caractères")
        print("Fichier sauvegardé : output/article_final.md")

if __name__ == "__main__":
    FlowJournaliste().kickoff()

bash

python3 flow_journalistes.py

Structured Output : forcer le format de sortie

Pour obtenir un résultat structuré (JSON, Pydantic) plutôt que du texte libre :

python

from pydantic import BaseModel
from crewai import Task

class Article(BaseModel):
    titre: str
    chapeau: str
    sections: list[str]
    conclusion: str

tache_structuree = Task(
    description="Écris un article sur l'IA générative",
    expected_output="Un article structuré",
    agent=redacteur,
    output_pydantic=Article,  # La classe, PAS une instance
    output_file="output/article.json",
)

Pièges classiques (v1.15.9)

`Context length exceeded` : l'historique de conversation dépasse la fenêtre du modèle. Passe respect_context_window=True (défaut) pour que CrewAI résume automatiquement, ou réduis la taille des descriptions.
API key manquante : SERPER_API_KEY non définie → la recherche web échoue silencieusement. Crée un compte gratuit sur serper.dev.
`max_iter` trop bas : si ton agent s'arrête après un seul appel d'outil, force max_iter=15 explicitement.
Ollama trop lent : passe à llama3.2:1b pour tester, ou gpt-4o-mini qui coûte 10x moins cher que GPT-4o.
Résultat en anglais : ajoute « en français » dans le backstory, le goal ET la description de la tâche. Utilise output_pydantic pour forcer un format.
`allow_code_execution` ne fonctionne plus : cette fonctionnalité est dépréciée. Utilise E2B ou Modal pour du sandbox de code.
Erreur `crewai_tools` introuvable : installe explicitement avec uv add "crewai[tools]". Le package n'est plus inclus par défaut.
Process hierarchical sans `manager_llm` : si tu utilises Process.hierarchical, tu DOIS fournir manager_llm="openai/gpt-4o" dans le constructeur de Crew.

Résumé

CrewAI v1.15.9 est une refonte majeure par rapport à la v0.80. Les concepts fondamentaux (Agent, Task, Crew) restent, mais l'API a changé : configuration LLM unifiée, projets JSON-first, Flows pour la production, structured output natif. Le pip install crewai de 2024 ne fonctionne plus — utilise uv tool install crewai et crewai create crew.

Tu as maintenant une base solide pour construire tes propres équipes d'agents IA. Pour approfondir : la doc officielle, les cookbooks, et le forum communautaire.