Guide

CrewAI : des équipes d'agents avec une répartition des rôles

CrewAI décrit le travail des agents comme une équipe : rôles, objectifs, outils. Crews et Flows, mémoire, tarifs, rédaction des rôles et erreurs fréquentes.

L'équipe CodeWorlds15 min de lecture ·

Pratique Python dans des leçons interactives avec un éditeur de code.

Crée un compte gratuit→
Dans cet article11

CrewAI décrit le travail des agents comme on décrirait une équipe de personnes : chacun reçoit un rôle, un objectif et un ensemble d'outils, et les tâches sont réparties entre eux. C'est un framework Python sous licence MIT, créé en 2023, avec une plateforme commerciale distincte pour le déploiement.

Deux modèles de travail à distinguer

Le framework propose deux mécanismes, et le choix entre eux décide si le projet se comporte de façon prévisible.

Les Crews sont des équipes d'agents qui travaillent ensemble sur une tâche. Vous définissez des rôles, des objectifs et des outils, et la répartition du travail découle des descriptions de rôles. Cela convient au travail dont le chemin vers le résultat n'est pas connu d'avance, par exemple analyser un sujet sous plusieurs angles.

Les Flows sont des pipelines pilotés par les événements, avec un état explicite et un ordre d'étapes défini. Vous décidez ce qui déclenche quoi et comment les données passent d'une étape à l'autre. Cela convient aux processus dont le déroulement est fixe et doit être reproductible.

Le framework a démarré en 2023 et est devenu un projet avec une grande communauté et une plateforme de déploiement distincte utilisée en entreprise. C'est important en pratique au moment de choisir : la documentation et les exemples abondent, et la plupart des problèmes que vous rencontrerez ont déjà été décrits par quelqu'un. Le prix de ce rythme est une API qui évolue d'une version à l'autre, épinglez donc la version dans votre fichier de dépendances plutôt que d'installer la dernière à chaque build.

L'erreur de débutant la plus courante est de construire une équipe d'agents là où un flow suffirait. Une équipe coûte plus cher, puisque chaque agent implique des appels de modèle distincts, et elle est plus difficile à diagnostiquer, car on ne sait pas lequel a fait le mauvais choix. Commencez par un flow et passez à une équipe quand l'ordre des étapes dépend vraiment des données.

Votre première crew

Bash
pip install crewai crewai-tools
export OPENAI_API_KEY=...
Python
from crewai import Agent, Task, Crew, Process

analyst = Agent(
    role="Market analyst",
    goal="Gather facts about competitors in the invoicing tools segment",
    backstory="You work from public data and cite a source for every number.",
    verbose=True,
)

writer = Agent(
    role="Editor",
    goal="Write a concise summary for the board",
    backstory="You write briefly, without jargon, always leading with the conclusion.",
)

research = Task(
    description="Find five competitors and describe their pricing model.",
    expected_output="A list of five companies with prices and a source for each.",
    agent=analyst,
)

summary = Task(
    description="From the gathered data, write a one page memo.",
    expected_output="A memo with the conclusion in the first paragraph.",
    agent=writer,
)

crew = Crew(
    agents=[analyst, writer],
    tasks=[research, summary],
    process=Process.sequential,
)

print(crew.kickoff())

Le champ expected_output est souvent sauté, et c'est la partie la plus importante de toute la définition. Sans lui, l'agent décide lui-même de ce que signifie « terminé », et les résultats dérivent d'une exécution à l'autre. Décrivez le format de sortie aussi précisément que vous le feriez à une personne qui réalise la tâche pour la première fois.

Comment une crew s'exécute

Le processus séquentiel exécute les tâches dans l'ordre, en passant chaque résultat comme contexte à la suivante. Il est prévisible et peu coûteux, puisque les appels au modèle suivent le nombre de tâches.

Le processus hiérarchique ajoute un agent gestionnaire qui répartit le travail et examine les résultats. Il se comporte mieux sur les tâches ambiguës, mais chaque transmission est un appel de modèle supplémentaire, donc la facture croît plus vite que le nombre d'agents ne le laisse croire.

Python
crew = Crew(
    agents=[analyst, writer],
    tasks=[research, summary],
    process=Process.hierarchical,
    manager_llm="gpt-5",
)

Une remarque pratique : le modèle gestionnaire peut différer de ceux qui travaillent. La gestion demande du raisonnement, l'exécution souvent non, donc un modèle plus puissant au sommet et un modèle moins cher dans les tâches peuvent diviser le coût par deux sans perte de qualité.

Outils et mémoire

Un agent sans outils ne peut que générer du texte. Les outils lui donnent accès à la recherche, aux fichiers, aux bases de données et à vos propres fonctions.

Python
from crewai.tools import tool

@tool("Check stock level")
def stock_level(sku: str) -> str:
    """Returns the number of units available for the given SKU."""
    return warehouse.fetch(sku)

analyst = Agent(role="...", goal="...", backstory="...", tools=[stock_level])

La description de l'outil décide si l'agent s'en saisit. Une phrase qui dit clairement quand l'appeler fonctionne mieux qu'une phrase qui dit seulement ce qu'il fait.

Limitez l'ensemble d'outils de chaque agent à ce dont son rôle a réellement besoin. Dix outils sur un seul agent, c'est un prompt plus long à chaque appel et des mauvais choix plus fréquents, alors que les répartir sur deux rôles améliore généralement les résultats à moindre coût.

La mémoire s'active avec un seul paramètre, memory=True sur la crew, mais sa forme a changé dans la ligne 1.x. Les trois couches séparées d'autrefois, mémoire à court terme, à long terme et d'entités, ont disparu. Une seule classe Memory les remplace, avec des portées organisées en arbre comme /project/alpha, où le modèle déduit la portée et l'importance de chaque fait stocké et où le rappel combine la similarité sémantique, la récence et l'importance. Activez-la délibérément, car le stockage persiste d'une exécution à l'autre et la question de l'endroit où ces données vivent revient, et sans votre propre modèle d'embeddings elle utilise OpenAI text-embedding-3-large.

Cette valeur par défaut compte précisément quand la question de l'emplacement du stockage est réelle, puisque chaque fait mémorisé part chez un fournisseur externe pour obtenir son vecteur. Une alternative auto-hébergée est BGE embeddings, publiée sous une licence qui autorise l'usage commercial et sans coût par token. Vous la payez en hébergeant le modèle et avec un piège au moment du changement : la dimension du vecteur diffère de celle par défaut, donc un stockage existant doit être recalculé et non complété.

Les Flows, ou quand l'ordre compte

Les Flows résolvent un problème que l'équipe d'agents ne résout pas : la reproductibilité. Une étape se déclenche en réponse à un événement, l'état passe explicitement d'une étape à l'autre, et vous savez ce qui s'exécute et dans quel ordre.

Python
from crewai.flow.flow import Flow, start, listen

class TicketHandling(Flow):
    @start()
    def classify(self):
        return {"category": classifier.run(self.state.content)}

    @listen(classify)
    def route(self, result):
        if result["category"] == "complaint":
            return complaints_crew.kickoff(inputs=result)
        return automatic_reply(result)

Cet agencement permet de mélanger les deux approches. Le flow gère le contrôle et décide de ce qui se passe, tandis qu'une crew d'agents exécute la partie où le chemin vers le résultat n'est pas connu d'avance. C'est généralement le meilleur compromis entre prévisibilité et flexibilité.

Gardez l'état du flow explicite, dans un seul objet, plutôt que dispersé dans des variables. Quand on diagnostique une panne, répondre à « quelles données cette étape a-t-elle reçues » doit prendre quelques secondes et non une demi-heure de lecture de logs.

Pour les processus plus longs, ajoutez une gestion des erreurs au niveau des étapes. Un appel d'API externe qui échoue une fois sur cent exécutions bloquera, s'il n'est pas géré, tout le flow et laissera la tâche dans un état indéfini.

Tarifs

Le framework est gratuit sous licence MIT et tourne sur votre propre serveur sans restriction. La partie payante est la plateforme pour déployer et surveiller les agents.

PlanCoûtLimiteConvient pour
Framework sur votre propre infrastructure0 USDaucuneFonctionnalités complètes, licence MIT
Plateforme AMP, plan Basic0 USD50 exécutions par mois, 2 automatisations, pas de dépassementExpériences et un seul processus
Plateforme AMP, plan Enterprisedevis personnaliséquota adapté au workflow, dépassement possibleConformité, SSO, RBAC, déploiement dans votre propre VPC

Il est utile de comprendre exactement ce que compte une exécution sur la plateforme. Une exécution est un passage à travers un processus, quel que soit le nombre d'agents qui y participent. La grille tarifaire a deux niveaux et rien entre les deux : un plan Basic avec cinquante exécutions par mois et un plan Enterprise chiffré individuellement. Il n'existe pas d'abonnement mensuel intermédiaire, donc la première étape au-delà du quota gratuit est une discussion commerciale. Ce qui se passe à la limite compte davantage : sur Basic, ces cinquante exécutions sont aussi un plafond strict, car aucun dépassement n'est vendu à ce niveau, et le nombre d'automatisations est limité à deux. Seul Enterprise obtient un quota adapté au workflow précis, plus un dépassement au-delà. Au volume d'une automatisation qui réagit à chaque ticket client, il est plus judicieux de faire tourner le framework sur votre propre infrastructure, où aucune limite ne s'applique, et de construire la supervision de votre côté.

La facture de tokens est distincte et domine généralement. Une crew de quatre agents avec mémoire peut faire bien plus d'une douzaine d'appels de modèle par tâche, chiffrez donc une seule exécution avant de rendre un processus permanent. À grande échelle, l'écart entre un modèle plus cher et un modèle moins cher dans les rôles de support se compte en centaines de dollars par mois.

Rédiger les rôles pour que l'agent fasse ce qu'il faut

Une description de rôle est l'équivalent, dans ce framework, d'un prompt système, et elle influence la qualité de la sortie plus que le choix du modèle. Trois éléments font la plus grande différence.

Le périmètre de compétence, c'est-à-dire ce que l'agent traite et ce qu'il ne traite pas. Une phrase comme « vous ne traitez que les données financières et vous transmettez les questions marketing » évite qu'un agent réponde à tout un peu.

La manière de travailler, c'est-à-dire comment il doit arriver à un résultat. « Vous citez une source pour chaque chiffre » ou « vous vérifiez l'actualité des données avant de répondre » change davantage le comportement qu'ajouter un adjectif au rôle.

Les contraintes énoncées explicitement. Les modèles réagissent mieux à des limites claires qu'à des encouragements généraux à faire attention. « Vous ne devinez pas les prix quand vous ne trouvez pas de source, vous écrivez no data available » fonctionne, « sois précis » non.

Python
analyst = Agent(
    role="Pricing analyst",
    goal="Establish current competitor prices with a source for each",
    backstory=(
        "You work only from public data. For every price you give the page address "
        "and the date checked. When you cannot find a price, you write 'no data' rather than estimate. "
        "You do not comment on strategy or product quality."
    ),
    max_iter=8,
)

Le paramètre qui plafonne le nombre de tours vaut la peine d'être défini dès le début. Sans lui, un agent qui ne parvient pas à clore une tâche continue d'essayer jusqu'à épuisement de la limite par défaut, et chaque tentative coûte.

Traitez les descriptions de tâches aussi sérieusement que les descriptions de rôles. Une tâche formulée « analysez le marché » produit un résultat aléatoire, car rien ne dit quand elle est terminée. Une tâche avec un format de sortie et un nombre d'éléments précisés produit un résultat reproductible.

CrewAI face aux alternatives

OutilPoint fortPoint faibleÀ choisir quand
CrewAIModèle de rôles lisible, démarrage rapide, valeurs par défaut senséesMoins de contrôle du flux qu'avec un grapheÉquipe d'agents avec une répartition claire du travail
LangGraphContrôle total du flux, état durable, pausesPlus de travail sur les cas simplesProcessus avec embranchements et validation humaine
LangChainLe plus grand ensemble d'intégrations, agent en une fonctionPlus de décisions à prendreApplication qui combine modèles et outils
n8nInterface visuelle, des centaines d'intégrations prêtesMoins flexible avec une logique complexeAutomatisation impliquant des non-techniciens

Ces outils se combinent aussi. Un flux n8n peut appeler une crew d'agents via votre propre API, et un graphe LangGraph peut posséder le tronçon qui nécessite une pause pour validation.

Le choix dépend de la façon dont le processus se décrit : comme une équipe avec des rôles ou comme un graphe avec des conditions. Pour le premier cas, CrewAI livre plus vite, pour le second un graphe est plus lisible et plus facile à tester.

Deux autres points de repère de la même famille méritent d'être connus. Agno mise sur la légèreté et la rapidité de construction d'un agent, il convient donc souvent mieux là où une équipe de rôles est excessive. CAMEL est né de la recherche sur des agents qui conversent entre eux et trouve sa place quand vous vous intéressez à la simulation ou à la génération de données plutôt qu'à la réalisation d'une tâche de production.

Comment savoir si ça marche

Un système d'agents sans mesure a l'air correct en démonstration et échoue sur des données réelles. L'évaluation se divise en trois questions, chacune mesurée différemment.

La sortie a-t-elle le bon format ? C'est la mesure la moins chère et la plus souvent sautée. Vingt exécutions, avec le décompte des sorties qui s'analysent ou passent en aval sans correction manuelle, attrapent la plupart des problèmes de description de tâche.

La sortie est-elle factuellement juste ? Il faut ici un ensemble de cas avec les réponses attendues, préparé une fois et relancé après chaque modification d'un rôle, d'une tâche ou d'un modèle. Il n'a pas besoin d'être grand, trente cas suffisent pour remarquer une régression.

Combien cela a-t-il coûté ? Additionnez les appels de modèle et les tokens par exécution, puis multipliez par le volume attendu. Ce chiffre est généralement celui qui surprend le plus, car une crew d'agents consomme plusieurs fois plus qu'un appel unique, et l'écart reste invisible tant que le processus tourne sur dix cas.

Activez la journalisation détaillée pendant le réglage et désactivez-la en production. Un enregistrement d'exécution avec le texte des prompts montre où l'agent a quitté le chemin, ce qui est rarement évident avec deux rôles qui coopèrent. En production, le même enregistrement coûte du stockage et risque de mettre des données dans des logs où vous ne le souhaitez pas.

Erreurs courantes

La première est de créer trop d'agents. Cinq rôles dans un premier projet produisent presque toujours un système où personne ne peut dire quel agent a fait le mauvais choix. Commencez avec un seul et ajoutez-en un deuxième quand le premier ne suit clairement plus.

La deuxième est l'absence de limite d'itérations. Un agent qui ne parvient pas à clore une tâche tournera en rond jusqu'à épuisement du budget. Fixez une limite de tours et considérez l'avoir atteinte comme un bug dans la description de la tâche.

La troisième est de rédiger des descriptions de rôles génériques. « Vous êtes un assistant utile » ne donne rien au modèle. Un rôle doit porter un périmètre de compétence, une manière de travailler et des contraintes énoncées explicitement.

La quatrième est de ne pas avoir de jeu de test. Modifier une description de rôle ou un modèle peut améliorer trois cas et en casser deux, et sans liste de comparaison personne ne le remarque avant la première réclamation.

La cinquième est de garder des secrets dans les descriptions d'agents. Tout ce qui est écrit dans une description de rôle ou de tâche arrive dans le prompt et dans les logs d'exécution.

FAQ

CrewAI est-il gratuit ?

Le framework est open source sous licence MIT et gratuit en usage commercial, sans limite d'exécutions sur votre propre infrastructure. La partie payante est la plateforme AMP de déploiement et de supervision, dont la grille tarifaire n'a que deux niveaux : un plan Basic à 0 USD avec 50 exécutions par mois, deux automatisations et aucun dépassement possible, et un plan Enterprise chiffré individuellement. Il n'existe aucun plan intermédiaire avec un prix d'abonnement publié.

CrewAI ou LangGraph ?

CrewAI livre plus vite quand la tâche se décrit comme une équipe avec une répartition des rôles. LangGraph donne un contrôle total du flux, un état durable et la possibilité de suspendre un processus pour une validation humaine, il convient donc mieux aux processus métier au déroulement fixe.

Combien coûte une exécution de crew ?

Cela dépend du nombre d'agents, des outils et du modèle. Une crew de trois agents avec mémoire fait généralement de huit à vingt appels de modèle par tâche, donc avec un modèle de gamme intermédiaire une exécution coûte quelques dizaines de centimes. Chiffrez-la sur dix cas réels avant de déployer.

Fonctionne-t-il avec d'autres modèles qu'OpenAI ?

Oui, il prend en charge des modèles de divers fournisseurs, dont Claude et des modèles locaux servis par Ollama. Changer revient à nommer un autre modèle dans la configuration de l'agent, même si les descriptions de rôles demandent généralement un réglage ensuite.

Est-il prêt pour la production ?

Oui, à deux conditions. Le processus a besoin de limites d'itérations et d'une gestion des erreurs, car sans elles un échec se termine par un blocage silencieux ou par une facture. Il faut aussi un ensemble de cas de test exécuté après chaque modification de prompt, car le comportement des agents évolue d'une manière difficile à remarquer.

La documentation se trouve sur docs.crewai.com, et le code source dans le dépôt GitHub.

À lire aussi