CrewAI : comment utiliser, workflow pas à pas

Introduction

CrewAI est un framework Python open source qui permet d'orchestrer des agents IA autonomes travaillant ensemble sur des tâches complexes. Contrairement à un agent unique, CrewAI structure la collaboration autour de rôles définis, de tâches séquentielles ou parallèles et d'outils partagés.

Dans ce tutoriel, vous allez construire un workflow multi-agent fonctionnel de A à Z :

• Installation de l'environnement
• Définition de deux agents spécialisés
• Création de leurs tâches et attribution d'outils
• Exécution du crew et analyse des résultats

Chaque étape inclut du code Python prêt à copier-coller.

À la fin, vous aurez un template réutilisable — veille automatisée, analyse de documents, génération de contenu, ou tout autre processus métier.

📦 Problème d'installation ? Si vous bloquez à l'étape d'installation, consultez notre guide d'installation complet de CrewAI pour diagnostiquer et résoudre le problème.

---

Résumé rapide

#	Étape	Commande / Fichier
1	Créer l'environnement	uv venv crewai_env
2	Installer les dépendances	uv pip install crewai crewai-tools
3	Définir les agents	agents.py
4	Définir les tâches	tasks.py
5	Assembler le crew	main.py
6	Exécuter	python main.py

---

Qu'est-ce que CrewAI ?

CrewAI repose sur trois concepts clés :

Les Agents

Une entité dotées d'un rôle précis (analyste, rédacteur, chercheur), d'un objectif et d'une backstory optionnelle qui influence son comportement.

Chaque agent peut utiliser des Tools — des fonctions qu'il appelle pour accomplir des actions concrètes (recherche web, lecture de fichier, appel d'API).

Les Tasks

Une unité de travail assignée à un agent. Elle contient une description, un attendu de output et, optionnellement, un agent destinataire par défaut.

Le Crew

Le conteneur qui rassemble agents et tâches. Il gère le flux d'exécution (séquentiel, parallèle ou hybride) et centralise le contexte partagé entre agents.

Pourquoi CrewAI et pas un script brut ?

Critère	Script LLM brut	CrewAI
Structure	Floue	Rôles, tâches, outils définis
Routage	Manuel	Automatique entre agents
Évolutivité	Limitée	Ajout d'agents simple
Débogage	Difficile	Logs transparents par agent

---

Prérequis et installation

Ce dont vous avez besoin

• Python 3.10+
• uv installé (pip install uv)
• Une clé API OpenAI, Anthropic ou Ollama dans votre variable d'environnement

Installation

# Créer et activer un environnement virtuel
uv venv crewai_env
source crewai_env/bin/activate  # Linux / macOS
# crewai_env\Scripts\activate  # Windows

# Installer CrewAI et les outils intégrés
uv pip install crewai crewai-tools

Structure du projet

crewai_project/
├── agents.py      # Définitions de vos agents
├── tasks.py       # Définitions de vos tâches
├── main.py        # Assemblage et exécution du crew
└── .env           # OPENAI_API_KEY=sk-...

Vérification rapide

# main.py
import os
from crewai import Agent, Crew, Task

print("CrewAI importé avec succès")
print(f"Version CrewAI : {__import__('crewai').__version__}")

python main.py
# → CrewAI importé avec succès
# → Version CrewAI : 0.80.0  (exemple)

---

Définir ses agents et ses tâches

Créer les agents

Ouvrez agents.py. Le pattern le plus simple et répandu : un chercheur + un rédacteur.

# agents.py
from crewai import Agent
from crewai_tools import SerpDevTool, FileReadTool

class ResearcherAgent(Agent):
    def __init__(self):
        super().__init__(
            role="Research Analyst",
            goal="Find the most relevant and recent information on the given topic",
            backstory=(
                "You are an experienced research analyst with a background "
                "in technology and business intelligence. You know how to "
                "find credible sources and synthesize complex information quickly."
            ),
            tools=[SerpDevTool()],
            verbose=True,
            allow_delegation=False
        )

class WriterAgent(Agent):
    def __init__(self):
        super().__init__(
            role="Content Writer",
            goal="Produce a clear, well-structured summary based on research findings",
            backstory=(
                "You are a professional content writer specialized in technical "
                "topics. Your writing is precise, accessible and optimized "
                "for a developer audience."
            ),
            tools=[FileReadTool()],
            verbose=True,
            allow_delegation=True
        )

Créer les tâches

Ouvrez tasks.py et liez chaque tâche à un agent.

# tasks.py
from crewai import Task

def research_task(agent):
    return Task(
        description=(
            "Research the latest developments in AI agent frameworks. "
            "Find 3 to 5 key trends, with sources and brief explanations. "
            "Focus on CrewAI, LangChain, and the broader multi-agent ecosystem."
        ),
        agent=agent,
        expected_output=(
            "A structured markdown list of trends with source URLs and "
            "2-sentence summaries for each."
        )
    )

def writing_task(agent, context=None):
    return Task(
        description=(
            "Using the research findings provided as context, write a concise "
            "technical summary (400 words) aimed at developers. "
            "Include a section on 'Why it matters' and one on 'Getting started'."
        ),
        agent=agent,
        context=context,
        expected_output=(
            "A 400-word markdown article with H2 sections, bullet points, "
            "and a clear conclusion."
        )
    )

🔑 Point clé : la tâche d'écriture reçoit le context de la tâche de recherche. CrewAI transmet automatiquement le output de la première tâche en entrée de la seconde.

---

Ajouter des tools utiles

Les outils étendent les capacités de vos agents au-delà du simple appel LLM. CrewAI propose un catalogue intégré via crewai_tools.

Outils intégrés courants

Tool	Rôle
SerpDevTool	Recherche web via SerpDev
FileReadTool	Lire un fichier local
FileWriteTool	Écrire un fichier
DirectoryReadTool	Lister le contenu d'un répertoire
GithubTool	Interagir avec des repositories GitHub
CalculatorTool	Calcul arithmétique

Créer un tool personnalisé

# tools.py
from langchain.tools import tool
from typing import List

@tool
def keyword_extractorTool(text: str) -> List[str]:
    """Extract keywords from a text string. Returns a list of keywords."""
    words = text.lower().split()
    keywords = [w.strip(".,!?;:()[]{}") for w in words if len(w) > 4]
    return list(dict.fromkeys(keywords))[:10]

# Attacher à un agent :
# tools=[keyword_extractorTool, SerpDevTool()]

---

Exécuter le workflow et interpréter les résultats

Assembler et lancer le crew

# main.py
import os
from dotenv import load_dotenv
from crewai import Crew, Process
from agents import ResearcherAgent, WriterAgent
from tasks import research_task, writing_task

load_dotenv()

# Initialiser les agents
researcher = ResearcherAgent()
writer = WriterAgent()

# Créer les tâches
research = research_task(researcher)
writing = writing_task(writer, context=[research])

# Assembler le crew
crew = Crew(
    agents=[researcher, writer],
    tasks=[research, writing],
    process=Process.sequential,
    verbose=True
)

# Lancer
result = crew.kickoff()

print("=== RÉSULTAT FINAL ===")
print(result.raw)

python main.py

Sortie attendue

[TOOL CALL]  ResearcherAgent → SerpDevTool → recherche "AI agent frameworks 2026"
[TOOL RESULT] 5 résultats retrievés
[AGENT]       ResearcherAgent → Synthèse des 5 tendances en markdown structuré
[CONTEXT]     → WriterAgent.receive_context()
[AGENT]       WriterAgent → Rédaction de l'article à partir du contexte reçu

=== RÉSULTAT FINAL ===
## Tendances frameworks d'agents IA
1. **Multi-agent orchestration** ...
[article complet]

Le verbose=True rend le flux entièrement transparent — idéal pour débugger ou présenter le fonctionnement à une équipe.

Interpréter le résultat

L'objet result retourné par crew.kickoff() contient :

• result.raw — le texte brut généré par le dernier agent
• result.pydantic — le résultat parsé en objet Python (si configuré sur la tâche)
• result.tasks_output — la sortie de chaque tâche individuelle

Pour inspecter les sorties intermédiaires :

for task_result in result.tasks_output:
    print(f"Tâche : {task_result.description}")
    print(f"Agent : {task_result.agent.role}")
    print(f"Output : {task_result.raw}\n")

---

Améliorer le workflow : logs, retries et garde-fous

Journal de logs persistant

import logging

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s — %(name)s — %(levelname)s — %(message)s",
    handlers=[
        logging.FileHandler("crew_execution.log"),
        logging.StreamHandler()
    ]
)

Retry automatique sur erreur

crew = Crew(
    agents=[researcher, writer],
    tasks=[research, writing],
    process=Process.sequential,
    max_retries=2,       # Retry 2 fois en cas d'erreur
    retry_delay=10,      # Attendre 10s entre chaque tentative
    verbose=True
)

Validation des outputs de tâche

def validate_output(task_output: str) -> bool:
    """Refuse les outputs de moins de 50 caractères."""
    return len(task_output.strip()) > 50

writing = Task(
    description="Rédige le résumé.",
    agent=writer,
    expected_output="Un texte d'au moins 200 mots.",
    output_validator=validate_output
)

Si la validation échoue après les retries, CrewAI lève une TaskException.

Limiter le nombre de tours

crew = Crew(
    agents=[researcher, writer],
    tasks=[research, writing],
    process=Process.sequential,
    max_iterations=5,   # Arrête après 5 tours par agent
    verbose=True
)

Surveillance avec callbacks

from crewai.callbacks import AgentCallbackHandler

class MyCallback(AgentCallbackHandler):
    def on_agent_step(self, agent, step_log):
        print(f"  → {agent.role} : étape {step_log['step']}")

crew = Crew(
    agents=[researcher, writer],
    tasks=[research, writing],
    process=Process.sequential,
    callbacks=[MyCallback()]
)

---

Cas d'usage pour démarrer

Trois patterns de départ à copier-coller et adapter.

1. Veille IA automatisée

Deux agents — un qui scrape les sources, un qui synthétise. Idéal pour alimenter une newsletter ou un canal Slack.

2. Analyse de documents multiples

Un agent lit 5 PDF ou articles, un second en extrait les points communs et les contradictions. Utile pour des revues de littérature ou des due diligence.

3. Génération de contenu SEO

Un agent fait la recherche de mots-clés et l'analyse concurrentielle, le second rédige un article optimisé.

⚡ Conseil : commencez toujours avec deux agents maximum, un flux séquentiel, et itérez à partir de la sortie réelle plutôt que du plan initial.

---

Questions fréquentes

CrewAI est-il gratuit ?

CrewAI est open source (licence MIT). Vous payez uniquement les appels LLM via votre clé API (OpenAI, Anthropic, Ollama…). Le module CrewAI Pro (gestion de flotte, monitoring avancé) est payant, mais pas nécessaire pour démarrer.

Quelle différence avec LangChain ?

LangChain est une bibliothèque de bas niveau pour chaîner des opérations LLM. CrewAI est une couche d'orchestration construite au-dessus — il structure des agents avec rôles et tâches. Les deux peuvent être utilisés ensemble.

Peut-on utiliser CrewAI sans OpenAI ?

Oui. Configurez OPENAI_API_BASE et OPENAI_MODEL_NAME dans votre .env, ou utilisez Anthropic, Ollama, Gemini via les intégrations officielles. CrewAI est agnostique au provider LLM.

Comment déboguer un agent qui délègue mal ?

Activez verbose=True sur l'agent incriminé. Si l'agent délègue trop ou pas assez, ajustez son goal (plus précis) et son backstory (plus directive). La délégation est souvent un problème de prompt, pas de code.

CrewAI supporte-t-il le parallélisme ?

Oui. Utilisez Process.parallel au niveau du Crew pour exécuter plusieurs tâches simultanément. Le mode hiérarchique (Process.hierarchical) ajoute un agent manager qui orchestre — réservé aux cas complexes.

---

Articles liés

Ce tutoriel vous a montré les bases de CrewAI. Pour aller plus loin :

• 📥 Approfondissez l'installation de CrewAI si ce n'est pas encore fait
• 🔍 Explorez les meilleurs frameworks d'agents IA pour situer CrewAI dans l'écosystème
• 🚀 Découvrez l'automation marketing avec agents pour un cas d'usage concret et monétisable