CrewAI : guide des agents, tâches, flows et déploiement

CrewAI est un framework qui permet de confier des tâches à des agents spécialisés, de les réunir en équipes et d’encadrer leur travail avec des flows. Vous définissez les responsabilités, les outils accessibles, les résultats attendus et les transitions du programme ; la fiabilité dépend ensuite des modèles, des contrôles et des permissions retenus.

Comprendre les briques avant de construire une équipe

Dans CrewAI, un agent associe un rôle, un objectif, des instructions et un modèle de langage. Une tâche décrit le travail demandé et le livrable attendu. Une crew rassemble les agents et les tâches selon un processus d’exécution.

Le flow intervient à un autre niveau : il organise les étapes de l’application. Vous pouvez y placer une validation de données, l’exécution d’une crew, une vérification en Python et une demande d’approbation. Cette séparation aide à distinguer les décisions confiées au modèle des règles imposées par votre logiciel.

Brique	Responsabilité	Exemple de conception
Agent	Exécuter un travail avec un rôle et des outils	Extraire les faits présents dans un dossier
Tâche	Définir une demande et son résultat attendu	Produire une liste de faits avec leurs sources
Crew	Organiser le travail des agents	Enchaîner extraction et rédaction
Flow	Piloter les étapes et l’état du programme	Valider le dossier avant de lancer l’équipe
Outil	Donner accès à une fonction externe	Lire un document autorisé

Ces briques ne représentent pas des collaborateurs humains. Donner un rôle de contrôleur à un agent ne prouve pas qu’il détectera les erreurs du rédacteur. Les deux peuvent partager les mêmes limites ou accepter une affirmation sans preuve.

Commencez par préciser ce qui justifie plusieurs agents. Si une extraction suivie d’un contrôle programmé répond au besoin, ajouter une équipe peut surtout multiplier les échanges. Le guide des systèmes multi-agents développe ce choix d’architecture.

Définir des rôles et des tâches vérifiables

Les principaux champs d’un agent comprennent role, goal, backstory, llm et tools. Des réglages comme allow_delegation, max_iter et max_execution_time encadrent son comportement. La documentation des agents, consultée le 24 octobre 2026, décrit leur portée.

Utilisez le rôle pour préciser une responsabilité, l’objectif pour définir la réussite et les instructions pour fixer les limites. Évitez les biographies fictives censées donner de l’autorité au modèle. Préférez une consigne opérationnelle : extraire uniquement les informations présentes, conserver leur provenance et signaler les éléments manquants.

Une tâche doit décrire son entrée, son travail et sa sortie. CrewAI utilise notamment description et expected_output ; le champ context permet de désigner les résultats de tâches précédentes. Les sorties structurées et les garde-fous figurent également dans la documentation des tâches.

Pour un dossier documentaire, demandez par exemple une liste d’affirmations accompagnées de leur référence, puis une synthèse fondée sur cette liste. Précisez que l’absence de source doit rester visible. Une consigne générale de qualité ne suffit pas à définir un résultat contrôlable.

Séparez les contrôles de forme des contrôles de fond. Votre code peut vérifier qu’un champ existe ou qu’un identifiant est valide. Vérifier qu’une affirmation correspond au document demande une comparaison avec la source. Une sortie structurée facilite les échanges entre étapes, sans garantir la véracité du contenu.

Choisir le processus d’exécution

CrewAI documente un processus séquentiel et un processus hiérarchique. Le premier suit l’ordre des tâches ; le second confie l’organisation à un responsable, configuré avec manager_llm ou manager_agent. Ces mécanismes sont détaillés dans la documentation des processus.

Critère	Séquentiel	Hiérarchique
Organisation	Ordre défini dans la configuration	Attribution pilotée par un responsable
Responsabilités	Affectations explicites	Répartition selon les capacités des agents
Diagnostic	Examiner chaque étape dans l’ordre	Examiner aussi les décisions de coordination
Usage à envisager	Chaîne de traitement connue	Répartition qui varie selon le dossier

Pour démarrer, choisissez le séquentiel. Vous pourrez identifier plus facilement la tâche qui perd une information ou produit une réponse inutilisable. N’introduisez un responsable que si la répartition dynamique répond à une difficulté observée.

La délégation mérite la même prudence. Elle peut être utile lorsqu’un agent doit demander une contribution spécialisée, mais chaque échange ajoute du contexte et du travail à examiner. Définissez les responsabilités et les conditions d’arrêt avant de l’activer.

Le choix du framework vient après celui de l’architecture. Le comparatif CrewAI et LangGraph aide à examiner leurs différences ; l’article sur les frameworks d’agents IA situe ces approches dans un panorama plus large.

Préparer l’environnement et le premier exercice

La documentation d’installation consultée le 24 octobre 2026 demande Python à partir de 3.10 et avant 3.14. Elle utilise uv pour installer la CLI et gérer le projet. Ces prérequis et les commandes ci-dessous proviennent du guide officiel d’installation.

Préparez aussi un accès au fournisseur de modèle choisi et les identifiants des éventuels services externes. Vérifiez leurs conditions d’utilisation, leurs limites et la destination des données. Le choix d’un fournisseur doit précéder l’envoi de documents confidentiels.

Pour le premier exercice, utilisez un court dossier non sensible. L’objectif proposé est de transformer une note en synthèse sourcée, sans navigation web, sans messagerie et sans écriture dans un logiciel métier. Ce périmètre permet d’examiner le travail des agents sans dépendre immédiatement de plusieurs intégrations.

Définissez le résultat attendu avant l’installation : une synthèse fidèle, les références au dossier et une liste des informations absentes. Conservez aussi une réponse de référence rédigée manuellement pour comparer les omissions et les ajouts.

Enfin, distinguez la CLI installée globalement de la bibliothèque utilisée par le projet. Une mise à jour de la première ne met pas automatiquement la seconde à jour. Conservez les fichiers de dépendances du projet pour pouvoir retrouver l’environnement qui a produit un résultat.

Installer et configurer la première crew

1. Vérifier Python et installer la CLI

Vérifiez votre interpréteur :

python3 --version

Si uv manque, la documentation propose cette installation sous macOS et Linux :

curl -LsSf https://astral.sh/uv/install.sh | sh

Sous Windows, elle donne :

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Installez ensuite la CLI et vérifiez sa présence :

uv tool install crewai
uv tool list

Si l’installation signale un problème de PATH, la commande documentée est :

uv tool update-shell

2. Générer le projet

La syntaxe officielle de création est :

crewai create crew <your_project_name>

Remplacez le nom entre chevrons par celui de votre projet. Ouvrez ensuite le dossier généré dans votre éditeur.

La documentation actuelle privilégie JSONC : les agents sont définis dans agents/ et l’équipe dans crew.jsonc. Les tutoriels utilisant crew.py, config/agents.yaml et config/tasks.yaml correspondent au mode classique, toujours pris en charge avec l’option --classic.

3. Adapter les fichiers générés

Pour l’exercice, définissez un agent d’extraction et un agent de synthèse. Le premier doit relever les faits et leurs références ; le second doit rédiger uniquement à partir de ce relevé. Commencez sans délégation.

Dans crew.jsonc, placez l’extraction avant la rédaction et rendez leur dépendance explicite. Conservez les identifiants cohérents entre les fichiers. Renseignez les variables d’entrée nécessaires et la configuration du modèle choisi.

Gardez les clés dans .env et vérifiez son exclusion du dépôt. Une clé ne doit apparaître ni dans les instructions des agents ni dans un exemple partagé.

4. Installer les dépendances et exécuter

Depuis la racine du projet :

crewai install
crewai run

Examinez le livrable et les étapes intermédiaires. Le premier succès à rechercher est une exécution compréhensible : entrées connues, tâches identifiables, sortie conservée et erreurs visibles. Une réponse élégante ne suffit pas à valider l’équipe.

Connecter les outils avec des droits limités

Un outil transforme une décision du modèle en appel logiciel. Sa description doit préciser sa fonction, ses arguments et ce qu’il retourne. La documentation des outils CrewAI présente les outils disponibles et leur utilisation avec les agents.

Ajoutez les outils progressivement. Commencez par une lecture limitée à un répertoire, puis introduisez les recherches ou les services métier nécessaires. Chaque connexion supplémentaire crée une nouvelle cause possible d’erreur : authentification, données périmées, indisponibilité ou résultat trop volumineux.

Pour un outil personnalisé, validez les arguments dans le code. Une consigne demandant de respecter un périmètre ne remplace pas une vérification effective du chemin, du compte ou de l’opération autorisée. Retournez des erreurs exploitables plutôt qu’un résultat ambigu que l’agent pourrait interpréter comme un succès.

L’appel d’outils doit aussi avoir un contrat de sortie : distinguez résultat vide, accès refusé et panne du service. Ces situations appellent des réponses différentes.

Si vous retenez une connexion MCP, examinez les outils exposés et les permissions du serveur avant de l’intégrer. Un protocole commun ne constitue pas une autorisation d’accès générale.

Réservez les actions sensibles à une étape contrôlée. Pour un envoi de message, présentez le destinataire et le contenu exacts à approuver. Pour une écriture métier, vérifiez l’état courant et empêchez les doublons. Une approbation portant seulement sur l’objectif reste trop vague.

Utiliser les flows pour encadrer l’application

Les flows disposent d’un état et de méthodes reliées par des événements. @start() définit une entrée, @listen() une réaction à une étape et @router() une orientation conditionnelle. La persistance est accessible avec @persist, selon la documentation des flows.

Voici un exemple pédagogique adapté de ces mécanismes. Il montre la séparation entre préparation et contrôle, sans appel à un modèle :

from crewai.flow.flow import Flow, listen, start
from pydantic import BaseModel


class EtatDossier(BaseModel):
    texte: str = ""
    statut: str = "nouveau"


class DossierFlow(Flow[EtatDossier]):
    @start()
    def preparer(self):
        self.state.texte = "Document de démonstration"
        self.state.statut = "prepare"
        return self.state.texte

    @listen(preparer)
    def verifier(self, texte):
        if not texte.strip():
            raise ValueError("Document vide")
        self.state.statut = "verifie"
        return self.state.statut


resultat = DossierFlow().kickoff()
print(resultat)

Dans une application, vous pourriez insérer la crew après la validation du document, puis contrôler sa sortie avant de la transmettre. Gardez les règles certaines dans le code : présence d’une entrée, format d’un identifiant, droit d’accès ou destination autorisée.

Définissez aussi un état métier explicite : dossier reçu, analyse terminée, validation attendue, publication effectuée. Évitez de stocker uniquement un historique de texte difficile à interpréter lors d’une reprise.

La persistance doit être testée avec les effets externes. Restaurer l’état d’un flow ne suffit pas à empêcher la répétition d’un envoi ou d’une écriture. Prévoyez un identifiant d’opération et vérifiez si l’action a déjà abouti avant de la recommencer.

Gérer le contexte, les connaissances et la mémoire

Le contexte utile à une tâche n’est pas nécessairement tout l’historique disponible. Transmettez les éléments nécessaires à son travail, avec leur provenance. Une synthèse trop compressée peut supprimer une réserve ; un dossier intégral peut masquer les passages décisifs.

Séparez trois catégories dans votre conception : les données de la demande, les documents de référence et les informations conservées entre exécutions. Elles n’ont ni la même durée de vie ni les mêmes règles d’accès.

Pour une synthèse documentaire, conservez une correspondance entre chaque affirmation et son passage source. Si un agent intermédiaire reformule les faits, transmettez aussi les références : le rédacteur doit pouvoir retrouver la preuve.

N’activez une mémoire durable qu’après avoir identifié ce qu’elle doit conserver et pourquoi. Définissez une durée de conservation, une procédure de suppression et une séparation entre utilisateurs. Une préférence utile dans un dossier peut devenir une instruction inappropriée dans un autre.

L’injection de prompt concerne également les documents consultés. Un texte externe peut demander de changer les règles ou d’utiliser un outil. Traitez-le comme une donnée à analyser et maintenez les autorisations dans l’application. Le guide Sécuriser un agent IA détaille ces protections.

Mesurer la qualité et le coût par dossier

Évaluez le traitement complet sur des dossiers représentatifs : documents incomplets, contradictions, sources absentes et outils indisponibles. Incluez des cas dans lesquels la bonne réponse consiste à demander une précision ou à refuser une action.

Mesurez séparément la fidélité aux sources, les omissions, la conformité du format et la réussite des opérations. Un résultat peut être correct sur le fond mais inutilisable par le logiciel suivant. Il peut aussi respecter parfaitement le format et contenir une affirmation fausse.

Comparez l’équipe à une solution plus simple sur les mêmes entrées. Gardez plusieurs agents si leur contribution améliore les résultats observés ou facilite un contrôle nécessaire. Une répartition séduisante sur le papier n’est pas une mesure.

Pour le budget, additionnez les appels aux modèles, les services externes, l’hébergement et le temps de revue. Rapportez cette dépense aux dossiers acceptés, en incluant les échecs et les reprises. Le calculateur de prix des modèles aide à estimer la partie liée aux tokens.

Prévoyez des limites d’itération, de durée et de relance. Conservez une trace des modifications de configuration et des résultats associés. Changez un élément à la fois lorsque vous cherchez l’origine d’une dégradation.

Déployer et surveiller le traitement

Vous pouvez exploiter votre application sur votre infrastructure ou examiner CrewAI AMP. Cette plateforme propose notamment déploiement géré, accès API et traces d’exécution, selon la présentation officielle de CrewAI AMP.

Critère	Infrastructure exploitée par votre équipe	CrewAI AMP
Environnement	Vous préparez et maintenez l’exécution	Infrastructure gérée par la plateforme
Intégration	Vous construisez le service d’accès	Accès API proposé
Supervision	Vous organisez journaux et alertes	Traces et journaux intégrés
Budget	Hébergement et exploitation à estimer	Conditions de l’offre à vérifier

Avant tout déploiement, reproduisez l’environnement local, séparez les secrets et définissez le responsable des incidents. Une application déployée doit pouvoir refuser une demande, s’arrêter proprement et conserver assez d’informations pour expliquer un échec.

Pour AMP, le guide officiel de déploiement documente cette séquence depuis le projet préparé :

crewai login
crewai deploy create
crewai deploy status
crewai deploy logs

La création détecte notamment les informations du dépôt et les variables du fichier .env destinées à la plateforme. Examinez donc leur contenu et leur destination avant cette opération.

En exploitation, suivez les erreurs, la durée, les reprises et le coût par traitement. Protégez les journaux : ils peuvent contenir des documents ou des résultats sensibles. Testez enfin le retour à une configuration précédente. Notre annuaire des agents et frameworks permet de poursuivre la comparaison des solutions.

Problèmes fréquents

La commande est introuvable. Vérifiez la présence de la CLI dans la liste des outils uv, puis appliquez la correction du PATH présentée dans l’installation. Rouvrez le terminal avant de poursuivre.

Les fichiers ne correspondent pas au tutoriel. Identifiez le format du projet : JSONC ou classique Python/YAML. Utilisez la documentation adaptée et évitez de mélanger les structures pendant le premier exercice.

Un agent ou une tâche est introuvable. Comparez les identifiants déclarés dans crew.jsonc et dans les fichiers d’agents. Vérifiez aussi que les dépendances de contexte désignent des tâches précédentes.

Le modèle répond, mais les outils échouent. Testez séparément l’authentification du service, les arguments et le format retourné. Une réponse textuelle réussie ne valide pas toute l’intégration.

La synthèse invente des informations. Examinez d’abord le relevé transmis au rédacteur. Si l’erreur existe déjà dans cette étape, renforcez la comparaison avec les documents et autorisez explicitement le signalement des absences.

Une reprise répète une action. Vérifiez la distinction entre état sauvegardé et opération externe accomplie. Ajoutez une protection contre les doublons avant de réactiver le traitement.

Checklist avant la mise en service

Pages liées

Questions fréquentes

Faut-il savoir programmer pour utiliser CrewAI ?

La configuration JSONC permet de décrire une équipe sans écrire toute son orchestration en Python. Il faut néanmoins comprendre les dépendances, les clés API et les erreurs d'exécution. La création d'outils spécifiques et l'exploitation autonome demandent des compétences de développement.

CrewAI fonctionne-t-il avec un modèle local ?

Cela dépend du fournisseur, de son interface et des capacités du modèle choisi. Vérifiez la compatibilité dans la documentation de la version installée, puis testez les appels d'outils et les sorties attendues. Un modèle capable de discuter peut échouer dans une boucle agentique.

Quelle différence entre une crew et un flow ?

Une crew regroupe des agents chargés de tâches communes. Un flow décrit le déroulement du programme, avec son état et ses transitions. Une application peut utiliser un flow pour encadrer plusieurs crews.

CrewAI est-il gratuit ?

Le framework est distribué sous licence MIT selon le relevé du site d'octobre 2026. Son utilisation peut cependant entraîner des dépenses de modèles, d'outils externes et d'hébergement. La plateforme CrewAI AMP constitue une offre distincte dont les conditions doivent être vérifiées.

Peut-on reprendre un traitement CrewAI après une interruption ?

Les flows disposent de mécanismes de persistance de leur état. Il faut aussi prévoir le comportement des outils déjà exécutés : restaurer un état ne garantit pas qu'une écriture externe ne sera jamais répétée. Testez les interruptions avant une mise en production.

CrewAI, guide de référence : équipes d'agents, tâches, outils, flows, déploiement