Comment utiliser CrewAI : guide complet de la première utilisation à l'agent productif

Introduction

CrewAI est un framework Python qui orchestre des agents IA autonomes collaborant sur des missions complexes.

Le framework repose sur cinq concepts :

• Agent — un exécutant avec un rôle précis
• Task — une mission assignée à un agent
• Crew — un ensemble d'agents + tasks + processus
• Process — le mode d'exécution des tasks
• Tool — les capacités externes de l'agent (recherche web, API, etc.)

Chaque concept est indépendant. Vous pouvez commencer simple et ajouter de la complexité au fur et à mesure.

Dans ce guide : votre premier agent, une crew complète avec deux agents, et les bases pour scaler.

Résumé rapide

Élément	Rôle	Clé à retenir
Agent	Exécutant avec rôle, objectif, backstory	Un agent = un rôle + un but + un contexte
Task	Mission assignée à un agent	Possède une description, un expected_output
Crew	Orchestrateur d'agents + tasks	Plusieurs agents partageant un même workflow
Process	Mode d'exécution (Sequential / Hierarchical / Consensual)	Définit comment les agents interagissent
Tool	Capacité externe (recherche, API, calcul)	Attribué à un ou plusieurs agents

Section 1 — Créer votre premier agent

Un agent CrewAI nécessite trois attributs : role, goal et backstory. CrewAI les injecte dans le prompt du modèle.

from crewai import Agent

researcher = Agent(
    role="Research Analyst",
    goal="Find and summarize the latest trends in the AI agent market",
    backstory="You are an experienced market analyst specializing in AI technologies. You have a critical eye for details and know how to extract actionable insights from raw data.",
    verbose=True
)

print(f"Agent créé : {researcher.role}")

Résultat : un agent fonctionnel. Assignez-lui des tasks directement ou intégrez-le dans une crew.

Pas encore installé ? Suivez notre guide Installer CrewAI.

Le mode Verbose

verbose=True affiche les logs détaillés à chaque exécution :

• Le prompt envoyé au modèle
• Les steps de reasoning de l'agent
• L'output produit

Gardez verbose=True en développement. En production, réduisez-le ou désactivez-le.

goal vs task.description

Ne confondez pas :

• goal — le « pourquoi » intrinsèque de l'agent (sa motivation)
• task.description — le « quoi » à exécuter (la mission)

Un agent peut réaliser plusieurs tasks sans perdre son identité.

Section 2 — Assembler une Crew

Une crew regroup agents, tasks et un processus d'exécution.

from crewai import Crew, Process

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task],
    process=Process.sequential,
    verbose=True
)

result = crew.kickoff()
print(result)

Les trois types de Process

Sequential — les tasks s'exécutent dans l'ordre de déclaration. La task N+1 ne commence qu'une fois la task N terminée. Idéal pour les workflows où chaque étape dépend de la précédente (collecte → analyse → rapport).

Hierarchical — un agent « manager » orchestre les autres. Il assigne les tasks, valide les outputs, contrôle le flux. Utilisez ce mode quand un superviseur doit coordonner plusieurs exécutants.

Consensual — les agents votent collectivement pour chaque décision. Plus coûteux en tokens, mais utile pour des décisions collégiales (sélection de candidats, choix de direction).

manager_agent = Agent(
    role="Project Manager",
    goal="Ensure the team delivers high-quality work on time",
    backstory="You are a senior project manager with 15 years of experience coordinating technical teams."
)

crew = Crew(
    agents=[manager_agent, researcher, writer],
    tasks=[research_task, write_task],
    process=Process.hierarchical,
    manager_agent=manager_agent
)

Conseil : commencez par Process.sequential. C'est le mode le plus prévisible et le plus simple à débugger. Passez à hierarchical quand vous avez besoin d'un contrôle centralisé.

Section 3 — Définir et exécuter des Tasks

Chaque task contient :

• description — ce qu'il faut faire
• agent (optionnel) — qui l'exécute
• expected_output — le format du résultat attendu

from crewai import Task

research_task = Task(
    description="Research the top 5 trends in AI agents for 2026. Include market size, key players, and emerging use cases.",
    agent=researcher,
    expected_output="Une liste structurée des 5 tendances avec : nom de la tendance, donnée chiffrée, source, implication pour un builder IA."
)

write_task = Task(
    description="Using the research provided, write a 500-word article summarizing the 5 AI agent trends.",
    agent=writer,
    expected_output="Un article de 500 mots en français, format Markdown.",
    depends_on=[research_task]
)

Dépendances entre tasks

depends_on crée une dépendance explicite. En mode sequential, elle renforce l'ordre. En mode hierarchical, elle garantit que la task ne démarre que quand ses dépendances sont fulfillées.

Sans depends_on, chaque agent traite sa task dès que le processus le permet — ce qui peut causer des erreurs si un agent attend des données qui ne sont pas encore produites.

Accéder aux outputs

result = crew.kickoff()

for task in crew.tasks():
    print(f"Task: {task.description[:50]}... | Output: {task.output}")

Section 4 — Ajouter et configurer des Tools

Les tools étendent les capacités de vos agents au-delà de la génération de texte.

Tools intégrés

from crewai.tools import SearchTools, DatabaseTools

researcher.add_tool(SearchTools.search_internet)
researcher.add_tool(DatabaseTools.search_database)

Custom tools avec BaseTool

from crewai.tools import BaseTool

class MyCustomTool(BaseTool):
    name: str = "content_optimizer"
    description: str = "Analyse la densité d'un mot-clé dans un texte"
    
    def _run(self, text: str, target_keyword: str) -> str:
        word_count = len(text.split())
        keyword_count = text.lower().count(target_keyword.lower())
        density = (keyword_count / word_count * 100) if word_count > 0 else 0
        
        if density < 0.5:
            return f"Densité trop faible ({density:.2f}%). Ajoutez plus d'occurrences."
        elif density > 3:
            return f"Densité trop élevée ({density:.2f}%). Réduisez les occurrences."
        else:
            return f"Densité optimale ({density:.2f}%)."

optimizer_tool = MyCustomTool()
writer.add_tool(optimizer_tool)

Les tools sont attachés à un agent, pas à la crew. Un agent sans tool ne peut pas accomplir de tâches nécessitant une capacité externe.

Section 5 — Configurer le Process

Process Sequential — mode pipeline

Idéal pour : extraction → transformation → chargement, veille → analyse → rapport.

crew = Crew(
    agents=[data_collector, analyzer, reporter],
    tasks=[collect_task, analyze_task, report_task],
    process=Process.sequential
)

Si une task échoue, les suivantes ne démarrent pas. Souvent souhaitable pour éviter de propager des erreurs.

Process Hierarchical — mode manager

Idéal pour : projet multi-équipes, revue par un pair senior, validation avant publication.

crew = Crew(
    agents=[senior_editor, writer_1, writer_2],
    tasks=[article_task_1, article_task_2, review_task],
    process=Process.hierarchical,
    manager_agent=senior_editor
)

Le manager assigne les tasks, reçoit les outputs, et décide si une task nécessite une itération.

Process Consensual — mode vote

Idéal pour : sélection collective (candidats, idées, solutions), brainstorming structuré.

crew = Crew(
    agents=[evaluator_1, evaluator_2, evaluator_3],
    tasks=[evaluate_candidates_task, vote_task],
    process=Process.consensual
)

Plus lent et coûteux, mais produit des décisions plus équilibrées.

Section 6 — Patterns avancés

Input et output des crews

result = crew.kickoff(inputs={
    "topic": "AI agents in healthcare",
    "audience": "developers and healthcare CTOs",
    "tone": "technical but accessible"
})

Les inputs sont disponibles dans chaque task via {context} ou directement dans les prompts des agents.

Callbacks

def on_task_complete(task, output):
    print(f"Task '{task.description}' terminée : {output}")

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task],
    process=Process.sequential,
    callback=on_task_complete
)

Conditional tasks

from crewai.conditions import Condition

review_task = Task(
    description="Review the article for factual accuracy",
    agent=senior_reviewer,
    condition=Condition(
        "confidence_score < 0.8",
        depends_on=[write_task]
    )
)

La task de review ne s'exécute que si le score de confiance est inférieur à 0.8.

Human-in-the-loop

from crewai.tools import HumanTool

human_approval = HumanTool(
    name="approve_article",
    description="Demande validation humaine avant publication"
)

publish_task = Task(
    description="Publish the article to the blog",
    agent=publisher,
    tools=[human_approval]
)

L'agent s'arrête et attend une entrée humaine. Utile pour les workflows de validation éditoriale.

Section 7 — Debugging et optimisation

Activer le mode Verbose

verbose=2 affiche tout : prompts système, tool calls, reasoning steps, output final.

researcher = Agent(
    role="Research Analyst",
    goal="Find and summarize the latest trends",
    backstory="...",
    verbose=2  # 0 = silence, 1 = info, 2 = debug
)

Logging avancé avec Carbon

from crewai import Crew
from crewaiCarbon import CarbonLogger

logger = CarbonLogger(project="my-ai-project", api_key="your-key")

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task],
    process=Process.sequential,
    logger=logger
)

Visualisez les traces d'exécution, identifiez les bottlenecks, et replayz des sessions pour débugger.

Diagnostiquer un agent qui ne fait rien

1. Vérifiez que la task a une description et un expected_output
2. Vérifiez que les dépendances (depends_on) sont satisfaites
3. Augmentez le niveau de verbose
4. Testez avec un modèle plus puissant ou un temperature plus élevé
5. Testez le tool isolément s'il y en a un assigné

Optimiser les performances

Levier	Impact	Recommandation
Model	Coût + qualité	GPT-4o pour les tâches complexes, GPT-4o-mini pour les tâches simples
Nbre d'agents	Latence	2-3 agents maximum au départ, ajoutez progressivement
Tools	Fiabilité	2-3 tools par agent maximum, désactivez les inutilisés
Memory	Context	Activez pour les tâches multi-turn, désactivez pour one-shot
Cache	Coût	Cachez les appels API répétitifs

Exemple concret : crew de veille IA

Création d'une crew qui (1) recherche les tendances de la semaine, (2) filtre les sources fiables, (3) rédige un briefing structuré.

from crewai import Agent, Crew, Task, Process
from crewai.tools import SearchTools, FileWriteTools

# Agents
scout = Agent(
    role="IA Trend Scout",
    goal="Identifier les 10 articles les plus significatifs sur les agents IA de la semaine",
    backstory="Analyste spécialisé en veille technologique avec 10 ans d'expérience.",
    tools=[SearchTools.search_internet],
    verbose=True
)

filter_agent = Agent(
    role="Source Quality Filter",
    goal="Filtrer les sources et ne garder que celles avec un DA > 50",
    backstory="Expert SEO et analyse de sources. Vous ne gardez que l'excellence.",
    verbose=True
)

writer = Agent(
    role="Brief Writer",
    goal="Rédiger un briefing de veille de 400 mots en français",
    backstory="Rédacteur spécialisé en veille IA, ancien rédacteur en chef de TechCrunch France.",
    verbose=True
)

# Tasks
scout_task = Task(
    description="Recherche les 10 articles les plus partagés sur 'AI agents' cette semaine.",
    agent=scout,
    expected_output="Tableau de 10 articles : titre, URL, DA, shares"
)

filter_task = Task(
    description="Ne garde que les articles dont le DA > 50. Score de pertinence 1-10.",
    agent=filter_agent,
    expected_output="Liste des 5 meilleurs articles avec score de qualité",
    depends_on=[scout_task]
)

write_task = Task(
    description="Briefing de 400 mots : titre accrocheur, 5 points clés, conclusion 2026.",
    agent=writer,
    expected_output="Brief Markdown de 400 mots",
    depends_on=[filter_task]
)

# Crew
veille_crew = Crew(
    agents=[scout, filter_agent, writer],
    tasks=[scout_task, filter_task, write_task],
    process=Process.sequential,
    verbose=True
)

result = veille_crew.kickoff()
print(result)

Résultat : un briefing de veille IA de 400 mots, basé sur des sources réelles, structuré et actionnable. Exécution complète en ~2-3 minutes avec GPT-4o-mini.

Questions fréquentes

Comment créer un agent CrewAI ?

Trois paramètres obligatoires : role, goal, backstory. Ajoutez optionnellement des tools et verbose=True.

Agent(
    role="Researcher",
    goal="Find trends",
    backstory="You are a data analyst..."
)

Quelle est la différence entre Task et Crew ?

• Task — une mission spécifique (description + expected output)
• Crew — le conteneur qui orchestre plusieurs agents et tasks avec un process d'exécution

Comment les agents communiquent-ils ?

• Sequential : via l'output des tasks précédentes (depends_on)
• Hierarchical : le manager reçoit et redistribue les outputs
• Consensual : vote collectif via un mécanisme de consensus intégré

Peut-on utiliser CrewAI sans API externe ?

Oui. CrewAI support Ollama et tout modèle compatible OpenAI API :

export OPENAI_API_BASE=http://localhost:11434/v1
export OPENAI_API_KEY=local

Évitez les modèles < 7B params pour des tâches complexes.

Comment débugger un agent qui ne répond pas ?

1. Activez verbose=2
2. Vérifiez que la task a une description et un expected_output
3. Vérifiez les dépendances avec depends_on
4. Testez le tool séparément s'il y en a un
5. Loggez task.output après chaque exécution

---

Vous avez les bases. Lancez votre première crew.

• CrewAI : le guide complet du framework
• Installer CrewAI sur votre machine
• Créer un agent IA avec Python
• CrewAI Tools intégrés