CrewAI : guide complet pour créer des agents IA en Python

Coordonner plusieurs agents IA pour accomplir des tâches complexes est difficile : chaque agent doit avoir un rôle précis, communiquer avec les autres et produire un résultat cohérent. CrewAI résout ce problème avec une abstraction claire et un modèle d'orchestration orienté équipe. Ce guide explique comment fonctionne CrewAI, comment l'installer, et comment construire un pipeline multi-agents fonctionnel en Python.

Résumé rapide

Critère	Valeur
Langage	Python
Version stable	0.80+ (2025)
Type	Framework multi-agents
Modèles supportés	OpenAI, Anthropic, Ollama, Groq, Azure, etc.
Licence	MIT
Idéal pour	Pipelines éditoriaux, veille, automatisation, RAG multi-étapes

Ce qu'est CrewAI et pourquoi l'utiliser

CrewAI est un framework Python open-source conçu pour orchestrer plusieurs agents IA travaillant en équipe. Chaque agent dispose d'un rôle, d'un objectif et d'outils. L'ensemble forme une "crew" (équipe) qui exécute des tâches selon un processus défini.

L'idée centrale est simple : certains problèmes sont trop complexes pour un seul agent. Un agent unique qui doit chercher des informations, les analyser, rédiger un rapport et le formater va rapidement atteindre ses limites en termes de contexte et de fiabilité. En décomposant le travail en tâches spécialisées confiées à des agents dédiés, CrewAI améliore la qualité et la maintenabilité du système.

Place dans l'écosystème : CrewAI se situe entre LangChain (couche bas niveau, chaînes de prompts) et AutoGen (communication bidirectionnelle entre agents). Il offre une API plus haut niveau que LangGraph, avec moins de configuration requise pour les cas d'usage courants. Il est particulièrement adapté aux workflows séquentiels ou hiérarchiques où les tâches s'enchaînent de manière prévisible.

Cas d'usage typiques :

Pipelines de veille concurrentielle (recherche → analyse → rapport)
Production de contenu éditorial (brief → rédaction → révision → SEO)
Analyse de données en plusieurs passes
Automatisation de workflows métier avec validation humaine optionnelle

CrewAI supporte nativement les principaux fournisseurs de modèles (OpenAI, Anthropic, Groq, Ollama pour le local) via LiteLLM, ce qui le rend portable.

Architecture et concepts fondamentaux

Les quatre briques de base

CrewAI repose sur quatre abstractions principales qui s'emboîtent pour former un système complet.

1. Agent

Un Agent est l'unité de base. Il encapsule :

un rôle (role) : qui est cet agent dans l'équipe
un objectif (goal) : ce qu'il cherche à accomplir
une histoire (backstory) : contexte pour guider son comportement
des outils (tools) : fonctions qu'il peut appeler (recherche web, lecture de fichiers, API)
un modèle (llm) : le LLM sous-jacent

from crewai import Agent
from crewai_tools import SerperDevTool

search_tool = SerperDevTool()

analyst = Agent(
    role="Analyste de marché",
    goal="Identifier les tendances clés sur un marché donné",
    backstory=(
        "Vous êtes un analyste senior spécialisé dans les marchés technologiques. "
        "Vous synthétisez des informations provenant de sources multiples pour "
        "produire des analyses actionnables."
    ),
    tools=[search_tool],
    llm="gpt-4o",
    verbose=True,
)

2. Task

Une Task définit un travail précis à réaliser par un agent. Elle contient :

une description (description) : ce qui doit être fait, avec le contexte nécessaire
un résultat attendu (expected_output) : format et contenu du livrable
l'agent assigné (agent) : qui exécute la tâche
un contexte optionnel (context) : résultats d'autres tâches à injecter

from crewai import Task

analysis_task = Task(
    description=(
        "Analysez le marché des frameworks d'agents IA en 2025. "
        "Identifiez les 5 principaux acteurs, leurs parts de marché estimées "
        "et les tendances d'adoption sur GitHub (étoiles, contributeurs)."
    ),
    expected_output=(
        "Un rapport structuré en Markdown avec : "
        "1) tableau comparatif des frameworks, "
        "2) analyse des tendances, "
        "3) recommandations pour les développeurs."
    ),
    agent=analyst,
)

3. Crew

La Crew assemble les agents et les tâches. Elle définit le mode d'exécution et orchestre le tout.

from crewai import Crew, Process

crew = Crew(
    agents=[analyst, writer],
    tasks=[analysis_task, writing_task],
    process=Process.sequential,  # ou Process.hierarchical
    verbose=True,
)

result = crew.kickoff()

4. Process

Le Process détermine comment les tâches sont exécutées :

Process.sequential : les tâches s'exécutent dans l'ordre, chaque résultat pouvant alimenter la suivante. C'est le mode par défaut, adapté aux pipelines linéaires.
Process.hierarchical : un agent manager coordonne les autres agents et décide de l'attribution des tâches. Nécessite un manager_llm.

Installation

pip install crewai crewai-tools

Pour les outils de recherche web :

pip install 'crewai[tools]'

Variables d'environnement à configurer :

export OPENAI_API_KEY="sk-..."
export SERPER_API_KEY="..."   # pour la recherche web

Outils disponibles

CrewAI s'intègre avec un écosystème d'outils (crewai_tools) :

Outil	Usage
`SerperDevTool`	Recherche web via Serper
`ScrapeWebsiteTool`	Extraction de contenu web
`FileReadTool`	Lecture de fichiers locaux
`CSVSearchTool`	Recherche dans des CSV
`CodeInterpreterTool`	Exécution de code Python
`RagTool`	Recherche dans une base vectorielle

Il est aussi possible de créer des outils personnalisés avec le décorateur @tool :

from crewai.tools import tool

@tool("Calculateur de score")
def score_calculator(metric: str, value: float) -> str:
    """Calcule un score normalisé pour une métrique donnée."""
    score = min(100, value * 10)
    return f"Score pour {metric} : {score}/100"

Configuration du modèle

CrewAI utilise LiteLLM en interne, ce qui permet de switcher facilement de modèle :

# OpenAI
agent = Agent(role="...", goal="...", backstory="...", llm="gpt-4o-mini")

# Anthropic
agent = Agent(role="...", goal="...", backstory="...", llm="claude-3-5-sonnet-20241022")

# Ollama (local)
agent = Agent(role="...", goal="...", backstory="...", llm="ollama/llama3.2")

Exemple concret : pipeline de veille concurrentielle

Ce pipeline analyse automatiquement les frameworks d'agents IA concurrents pour produire un rapport hebdomadaire.

import os
from crewai import Agent, Task, Crew, Process
from crewai_tools import SerperDevTool, ScrapeWebsiteTool

os.environ["OPENAI_API_KEY"] = "sk-..."
os.environ["SERPER_API_KEY"] = "..."

# Outils
search = SerperDevTool()
scraper = ScrapeWebsiteTool()

# Agent 1 : Chercheur
researcher = Agent(
    role="Chercheur en veille technologique",
    goal="Trouver les dernières informations sur les frameworks d'agents IA",
    backstory=(
        "Expert en veille technologique, vous collectez des données fiables "
        "depuis GitHub, Hacker News, et les blogs techniques majeurs."
    ),
    tools=[search, scraper],
    llm="gpt-4o-mini",
    max_iter=5,
)

# Agent 2 : Analyste
analyst = Agent(
    role="Analyste produit",
    goal="Synthétiser les données collectées en insights actionnables",
    backstory=(
        "Analyste produit senior, vous transformez des données brutes en "
        "recommandations claires pour les équipes de développement."
    ),
    llm="gpt-4o",
)

# Tâche 1 : Collecte
research_task = Task(
    description=(
        "Recherchez les 5 principaux frameworks d'agents IA open-source en 2025 : "
        "LangGraph, CrewAI, AutoGen, LangChain Agents, OpenClaw. "
        "Pour chacun, trouvez : étoiles GitHub actuelles, date du dernier commit, "
        "nombre de contributeurs, version stable actuelle."
    ),
    expected_output=(
        "Un JSON structuré avec les métriques de chaque framework."
    ),
    agent=researcher,
)

# Tâche 2 : Analyse (reçoit le contexte de la tâche 1)
analysis_task = Task(
    description=(
        "À partir des données collectées, rédigez un rapport de veille en Markdown. "
        "Incluez : tableau comparatif, analyse des tendances d'adoption, "
        "et 3 recommandations concrètes pour un développeur qui choisit un framework."
    ),
    expected_output=(
        "Rapport Markdown complet avec titre, tableau, analyse (300 mots), recommandations."
    ),
    agent=analyst,
    context=[research_task],
)

# Crew
crew = Crew(
    agents=[researcher, analyst],
    tasks=[research_task, analysis_task],
    process=Process.sequential,
    verbose=True,
)

result = crew.kickoff()
print(result.raw)

Ce pipeline produit un rapport structuré en deux passes : le chercheur collecte les données, l'analyste les synthétise. L'injection de contexte via context=[research_task] garantit que l'analyste travaille sur les données fraîches du chercheur.

Bonnes pratiques et limites

Erreurs fréquentes à éviter :

Backstory trop vague : une backstory générique produit un comportement générique. Décrivez précisément l'expertise et le style de l'agent.
Trop d'agents pour des tâches simples : 2-3 agents suffisent pour la majorité des cas. Chaque agent supplémentaire ajoute de la latence et du coût.
Oublier max_iter : sans limite d'itérations, un agent peut boucler. Fixez max_iter=5 ou max_iter=10 selon la complexité.
Tâches mal découpées : une tâche trop large produit des résultats flous. Chaque tâche doit avoir un périmètre clair et un seul livrable.

Limites connues :

Le mode Process.hierarchical consomme davantage de tokens (le manager re-planifie à chaque étape).
La gestion d'état entre exécutions n'est pas native : il faut implémenter sa propre persistance.
Les erreurs d'outils peuvent bloquer un agent sans fallback automatique.

Optimisations :

Utilisez gpt-4o-mini pour les agents de collecte et réservez les modèles puissants aux tâches d'analyse.
Activez cache=True sur les tâches qui appellent des outils coûteux pour éviter les appels redondants.
Testez chaque agent isolément avant d'assembler la crew complète.

FAQ

CrewAI est-il gratuit ?

Oui, CrewAI est open-source sous licence MIT. Le framework lui-même ne coûte rien. Les coûts proviennent des API de modèles utilisés (OpenAI, Anthropic, etc.) et des outils tiers (Serper pour la recherche web, par exemple). Il est possible d'utiliser CrewAI entièrement gratuitement avec Ollama et des modèles locaux.

Quelle est la différence entre CrewAI et LangGraph ?

LangGraph est un framework bas niveau basé sur des graphes d'états, adapté aux workflows complexes avec boucles et conditions. CrewAI propose une abstraction plus haut niveau (Agent, Task, Crew) qui demande moins de configuration. LangGraph offre plus de contrôle, CrewAI est plus rapide à mettre en œuvre pour les cas d'usage courants.

Peut-on utiliser CrewAI avec des modèles locaux ?

Oui. CrewAI passe par LiteLLM, ce qui permet d'utiliser Ollama, LM Studio ou tout serveur compatible OpenAI. Exemple : llm="ollama/llama3.2". Les performances dépendent du modèle local choisi et du matériel disponible.

Comment gérer les erreurs d'outils dans CrewAI ?

Par défaut, un agent réessaie automatiquement en cas d'échec d'outil. Vous pouvez configurer max_iter pour limiter les tentatives. Pour une gestion plus fine, wrappez vos outils personnalisés dans un bloc try/except et renvoyez un message d'erreur explicite que l'agent peut interpréter.

CrewAI supporte-t-il le streaming des réponses ?

Depuis la version 0.70+, CrewAI supporte le streaming via le paramètre step_callback sur la Crew. Cela permet de recevoir les étapes intermédiaires en temps réel, utile pour les interfaces utilisateur qui affichent la progression.

CrewAI : guide complet pour créer des agents IA en Python

CrewAI : guide complet pour créer des agents IA en Python

Résumé rapide

Ce qu'est CrewAI et pourquoi l'utiliser

Architecture et concepts fondamentaux

Les quatre briques de base

1. Agent

2. Task

3. Crew

4. Process

Installation

Outils disponibles

Configuration du modèle

Exemple concret : pipeline de veille concurrentielle

Bonnes pratiques et limites

FAQ

Articles liés

Restez informé sur les agents IA

Articles liés