CrewAI avec Claude : équipe d’agents pour recherche marché

Ce que vous saurez faire à la fin

1. Installer et configurer CrewAI avec Claude (claude-sonnet-4-6) via litellm en moins de 15 minutes
2. Créer une équipe de 3 agents spécialisés (Researcher, Analyst, Writer) avec rôles, objectifs et backstories réalistes
3. Définir des tasks séquentielles produisant un rapport de marché structuré
4. Lancer une étude de marché complète sur un secteur sénégalais (mobile money, logistique, agro-business)
5. Estimer le coût d’une exécution Crew et optimiser la consommation de tokens (cache, contexte)

Durée : 3h. Pré-requis : Python 3.10+, clé API Anthropic, 5 000 FCFA de crédit pour les premiers tests, connexion stable, éditeur VS Code.

Étape 1 — Pourquoi CrewAI plutôt qu’un seul agent ?

Un agent unique répond bien à une question simple. Pour une étude de marché complète (collecte, analyse SWOT, rédaction d’un rapport pour un dirigeant de PME à Dakar), l’agent unique perd le fil : il oublie les sources, mélange les chiffres, produit un texte décousu. CrewAI résout ce problème en répartissant la charge cognitive entre plusieurs agents spécialisés qui se passent leurs résultats. Pour une PME sénégalaise, cela signifie un livrable propre en moins d’une heure pour un coût compris entre 800 et 3 000 FCFA selon la profondeur.

Étape 2 — Installation et configuration

python -m venv crewai-env
source crewai-env/bin/activate  # Linux/Mac
# crewai-env\Scripts\activate   # Windows

pip install crewai==0.80.0 crewai-tools litellm anthropic python-dotenv
pip install duckduckgo-search beautifulsoup4

# Vérification
python -c "import crewai; print(crewai.__version__)"

Créez un fichier .env à la racine pour stocker vos clés sans les exposer dans le code source :

ANTHROPIC_API_KEY=sk-ant-api03-VOTRE_CLE
SERPER_API_KEY=optionnel_pour_recherche_web

Étape 3 — Configurer Claude comme LLM via litellm

CrewAI utilise litellm comme couche d’abstraction. Pour pointer vers Claude, on précise le préfixe anthropic/ devant le nom du modèle. C’est la méthode officielle recommandée depuis CrewAI 0.70.

import os
from dotenv import load_dotenv
from crewai import Agent, Task, Crew, Process, LLM

load_dotenv()

# Configuration Claude pour toute la Crew
claude_llm = LLM(
    model="anthropic/claude-sonnet-4-6",
    temperature=0.3,
    max_tokens=4096,
    api_key=os.getenv("ANTHROPIC_API_KEY")
)

# Pour les tâches plus simples (résumés), Haiku suffit
claude_haiku = LLM(
    model="anthropic/claude-haiku-4-5",
    temperature=0.2,
    max_tokens=2048
)

Étape 4 — Définir l’agent Researcher

Le Researcher cherche les informations brutes : taille de marché, acteurs clés, réglementation OHADA. On lui donne un rôle, un objectif et une backstory qui orientent son style.

from crewai_tools import SerperDevTool, WebsiteSearchTool

search_tool = SerperDevTool()  # nécessite SERPER_API_KEY

researcher = Agent(
    role="Analyste de marché Afrique de l'Ouest",
    goal="Collecter des données factuelles et chiffrées sur le marché {sujet} au Sénégal",
    backstory=(
        "Tu es un consultant basé à Dakar, 10 ans d'expérience auprès "
        "de PME sénégalaises. Tu connais les sources locales : ANSD, BCEAO, "
        "DPEE, presse spécialisée (Jeune Afrique, Financial Afrik). "
        "Tu cites toujours tes sources et donnes des chiffres en FCFA."
    ),
    tools=[search_tool],
    llm=claude_llm,
    verbose=True,
    allow_delegation=False,
    max_iter=5
)

Étape 5 — Définir l’agent Analyst

analyst = Agent(
    role="Analyste stratégique senior",
    goal="Transformer les données brutes en analyse SWOT exploitable par un dirigeant de PME",
    backstory=(
        "Diplômé HEC Paris, ancien consultant McKinsey Casablanca. "
        "Tu maîtrises le cadre OHADA, la fiscalité sénégalaise (TVA 18%, "
        "IS 30%) et les contraintes de financement local (taux BCEAO, "
        "garanties DER). Tu produis des analyses concises, actionnables."
    ),
    llm=claude_llm,
    verbose=True,
    allow_delegation=False,
    max_iter=3
)

Étape 6 — Définir l’agent Writer

writer = Agent(
    role="Rédacteur de rapports exécutifs",
    goal="Rédiger un rapport de 3 pages clair, structuré, en français professionnel",
    backstory=(
        "Tu rédiges depuis 8 ans pour des dirigeants ouest-africains. "
        "Style direct, phrases courtes, pas de jargon. Tu structures "
        "toujours : résumé exécutif, contexte, analyse, recommandations, "
        "annexes. Tu utilises FCFA et formats locaux (1 234 567 FCFA)."
    ),
    llm=claude_llm,
    verbose=True,
    allow_delegation=False
)

Étape 7 — Créer les tasks séquentielles

task_recherche = Task(
    description=(
        "Recherche complète sur le marché {sujet} au Sénégal en 2026. "
        "Inclus : taille du marché en FCFA, principaux acteurs (Wave, Orange "
        "Money, YAS Money (ex-Free Money) pour mobile money), parts de marché, réglementation "
        "BCEAO/ARTP, tendances 2024-2026. Cite tes sources."
    ),
    expected_output="Document brut de 800-1200 mots avec chiffres et sources",
    agent=researcher
)

task_analyse = Task(
    description=(
        "À partir du document de recherche, produis une analyse SWOT "
        "(Forces, Faiblesses, Opportunités, Menaces) pour une PME sénégalaise "
        "qui veut entrer sur ce marché avec 50 millions FCFA de capital. "
        "Identifie 3 segments porteurs et 3 risques majeurs."
    ),
    expected_output="Analyse SWOT structurée + 3 recommandations stratégiques",
    agent=analyst,
    context=[task_recherche]
)

task_redaction = Task(
    description=(
        "Rédige un rapport exécutif de 3 pages destiné au DG d'une PME "
        "à Dakar. Structure : 1) Résumé exécutif (200 mots), 2) Marché "
        "et acteurs, 3) Analyse SWOT, 4) Recommandations chiffrées en FCFA, "
        "5) Plan d'action 90 jours. Format Markdown."
    ),
    expected_output="Rapport Markdown complet, prêt à imprimer",
    agent=writer,
    context=[task_recherche, task_analyse],
    output_file="rapport_marche.md"
)

Étape 8 — Assembler et lancer la Crew

crew = Crew(
    agents=[researcher, analyst, writer],
    tasks=[task_recherche, task_analyse, task_redaction],
    process=Process.sequential,
    verbose=True,
    memory=True,  # mémoire partagée entre agents
    cache=True    # cache des résultats d'outils
)

if __name__ == "__main__":
    resultat = crew.kickoff(inputs={"sujet": "mobile money"})
    print("\n===== RAPPORT FINAL =====")
    print(resultat)
    print(f"\nTokens utilisés : {crew.usage_metrics}")

Étape 9 — Sequential vs Hierarchical : quel process choisir ?

CrewAI propose deux modes d’orchestration. Le tableau suivant aide à choisir selon le cas d’usage PME.

Critère              | Sequential          | Hierarchical
---------------------|---------------------|----------------------
Complexité           | Faible à moyenne    | Élevée
Coût tokens          | 800 à 3 000 FCFA    | 3 000 à 12 000 FCFA
Manager LLM          | Non                 | Oui (claude-opus-4-7)
Cas d'usage PME      | Étude marché, audit | Plan stratégique 5 ans
Temps d'exécution    | 2 à 5 minutes       | 8 à 20 minutes
Fiabilité résultat   | Très bonne          | Variable (manager)

Pour 90 % des cas PME, le mode Sequential suffit largement.

Étape 10 — Optimiser le coût avec le prompt caching

Claude propose un cache de prompts qui réduit le coût de 90 % sur les tokens répétés. Pour CrewAI, on l’active via le paramètre cache_control dans les backstories longues réutilisées.

from anthropic import Anthropic

# Wrapper personnalisé pour activer le cache
class CachedClaudeLLM(LLM):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.extra_headers = {"anthropic-beta": "prompt-caching-2024-07-31"}

# Économie typique sur une étude marché : 2 100 FCFA → 600 FCFA

Étape 11 — Ajouter un outil maison (calculateur FCFA)

from crewai.tools import tool

@tool("Convertisseur FCFA")
def convertir_fcfa(montant: float, devise_source: str) -> str:
    """Convertit un montant vers FCFA. Devises : EUR, USD, GBP."""
    taux = {"EUR": 655.957, "USD": 605.0, "GBP": 770.0}
    if devise_source not in taux:
        return f"Devise {devise_source} non supportée"
    fcfa = montant * taux[devise_source]
    return f"{montant} {devise_source} = {fcfa:,.0f} FCFA".replace(",", " ")

# Ajout à l'analyste
analyst.tools = [convertir_fcfa]

Étape 12 — Lancer en production avec logging

import logging
from datetime import datetime

logging.basicConfig(
    filename=f"crew_run_{datetime.now():%Y%m%d_%H%M}.log",
    level=logging.INFO,
    format="%(asctime)s | %(levelname)s | %(message)s"
)

try:
    resultat = crew.kickoff(inputs={"sujet": "logistique urbaine Dakar"})
    logging.info(f"Succès. Tokens: {crew.usage_metrics}")
except Exception as e:
    logging.error(f"Échec Crew : {e}")
    raise

Étape 13 — Cas d’usage concret : marché de la logistique à Dakar

En lançant crew.kickoff(inputs={« sujet »: « livraison du dernier kilomètre Dakar »}), on obtient en 4 minutes un rapport identifiant Yobante Express, Paps, Kamtar comme acteurs principaux, un marché estimé à 18 milliards FCFA avec une croissance de 22 %/an, et trois opportunités : zones péri-urbaines (Pikine, Guédiawaye), niche froid pour pharmacies, et white-label pour e-commerçants Jumia. Coût total de l’exécution : 1 850 FCFA.

Étape 14 — Déploiement : passer du notebook à un service

from fastapi import FastAPI, BackgroundTasks
from pydantic import BaseModel

app = FastAPI()

class DemandeEtude(BaseModel):
    sujet: str
    email_client: str

@app.post("/etude")
async def lancer_etude(demande: DemandeEtude, bg: BackgroundTasks):
    bg.add_task(executer_crew, demande.sujet, demande.email_client)
    return {"statut": "lancé", "delai": "5 minutes"}

def executer_crew(sujet: str, email: str):
    resultat = crew.kickoff(inputs={"sujet": sujet})
    # envoi email avec rapport en pièce jointe
    envoyer_rapport(email, resultat)

Erreurs classiques à éviter

• Erreur : oublier le préfixe anthropic/ dans le nom du modèle. CrewAI bascule alors sur OpenAI par défaut et plante avec une erreur cryptique de clé API manquante.
• Erreur : backstories trop longues sans cache. Une backstory de 500 mots par agent multipliée par 10 itérations coûte 8 fois plus cher que nécessaire. Activez le prompt caching.
• Erreur : allow_delegation=True par défaut. Les agents se passent les questions à l’infini. Désactivez-le sauf besoin explicite.
• Erreur : pas de max_iter. Un agent peut boucler 25 fois sur le même outil et brûler 15 000 FCFA en une exécution.
• Erreur : ignorer crew.usage_metrics. Sans tracking, vous découvrez la facture mensuelle Anthropic en panique.
• Erreur : verbose=True en production. Logs énormes, risque de fuite de données clients dans les fichiers texte.

Checklist déploiement CrewAI Claude

✓ Python 3.10+ et venv isolé créé
✓ crewai 0.80+ et litellm installés
✓ Clé ANTHROPIC_API_KEY dans .env (pas en dur)
✓ Modèle préfixé anthropic/claude-sonnet-4-6
✓ Chaque agent a role, goal, backstory clairs
✓ max_iter défini sur chaque agent (3 à 5)
✓ allow_delegation=False sauf besoin
✓ Tasks chaînées via context=[task_precedente]
✓ Process.sequential pour 90% des cas
✓ memory=True et cache=True activés
✓ Prompt caching pour backstories longues
✓ Logging fichier avec rotation quotidienne
✓ Suivi crew.usage_metrics après chaque run
✓ Budget mensuel Anthropic configuré dans console
✓ Tests sur 3 sujets différents avant production