CrewAI installation guide: setup Python pas à pas

Introduction

CrewAI est un framework Python open-source qui orchestre des agents IA autonomes sur des tâches complexes. Conçu pour les développeurs, il simplifie les pipelines multi-agents : attribution de rôles, partage de tâches, exécution séquentielle ou parallèle.

Dans ce guide : installation complète, environnement virtuel, dépendances, vérification et premier run d'un agent minimal.

---

Ce que vous allez apprendre

• Installer CrewAI sur votre machine
• Configurer un environnement virtuel propre
• Connecter un provider LLM (OpenAI, Anthropic ou Ollama)
• Lancer votre premier agent en 5 minutes

Temps estimé : ~3 minutes | Python minimum : 3.10

---

Qu'est-ce que CrewAI ?

Trois concepts centraux :

Concept	Rôle
Agent	Un rôle avec objectif et backstory
Task	Une tâche assignée à un agent
Crew	Une équipe d'agents qui collaborent

CrewAI se distingue de LangChain pur par sa simplicité de configuration. Définissez vos agents en YAML ou Python, assignez des tâches, contrôlez l'exécution.

Cas d'usage courants

• Veille automatique : agents qui scrutent des sources et synthétisent
• Rédaction multi-format : recherche → rédaction → relecture
• Analyse de données : extraction, transformation, interprétation
• Support client : routing intelligent vers des agents experts

Compatible avec OpenAI, Anthropic, Azure et Ollama (local).

---

Prérequis système

Python

Python 3.10+ requis. Vérifiez :

python3 --version

Version inférieure à 3.10 ? Installez via pyenv (Linux/macOS) ou l'installeur officiel (Windows).

pip

Vérifiez et mettez à jour si nécessaire :

python3 -m pip --version
python3 -m pip install --upgrade pip

OS supportés

• Linux : Ubuntu 20.04+, Debian 11+
• macOS : 12+ (Homebrew ou python.org)
• Windows : Python depuis le Microsoft Store ou python.org ; WSL2 recommandé

Ressources nécessaires

• Disque : ~300 Mo (package + dépendances)
• RAM : 4 Go minimum ; 8 Go+ si Ollama local

---

Installation de CrewAI avec pip

Étape 1 — Créer un environnement virtuel

N'installez jamais CrewAI dans l'environnement global. Utilisez un environnement virtuel pour isoler les dépendances.

python3 -m venv crewai-env
source crewai-env/bin/activate    # Linux/macOS
crewai-env\Scripts\Activate.ps1    # Windows PowerShell

Vérifiez : (crewai-env) doit apparaître dans votre prompt.

Étape 2 — Installer CrewAI

pip install crewai

Installation : ~1-2 minutes. Inclut LangChain, Pydantic, instructor.

Options :

# Dernière version bêta
pip install crewai --pre

# Avec dépendances d'outils tierces
pip install "crewai[tools]"

Étape 3 — Installer un provider LLM

CrewAI abstractise les LLMs via LangChain. Installez le package correspondant :

pip install langchain-openai        # OpenAI (par défaut)
pip install langchain-anthropic     # Anthropic (Claude)
pip install langchain-ollama        # Ollama (local, gratuit)

Ce guide utilise OpenAI. Préparez votre clé API (OPENAI_API_KEY).

---

Vérifier l'installation

Import et versions

import crewai
import langchain
import langchain_openai

print(f"CrewAI: {crewai.__version__}")
print(f"LangChain: {langchain.__version__}")

Connexion LLM

import os
from langchain_openai import ChatOpenAI

os.environ["OPENAI_API_KEY"] = "votre-clé-api-ici"

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
response = llm.invoke("Dis 'OK' en un mot")
print(response.content)  # → OK

OK ? Installation fonctionnelle.

---

Configurer les variables d'environnement

Créez un fichier .env à la racine du projet :

# .env
OPENAI_API_KEY=votre-clé-api-openai

Chargez avec python-dotenv :

pip install python-dotenv

from dotenv import load_dotenv
load_dotenv()

import os
print(os.environ.get("OPENAI_API_KEY"))

⚠️ Sécurité : ajoutez .env à votre .gitignore. Ne commitez jamais de clé API.

---

Premier projet CrewAI — agent minimal

Structure

mon-projet-crewai/
├── .env
├── .gitignore
├── agent_simple.py
└── requirements.txt

Le code

# agent_simple.py
import os
from dotenv import load_dotenv
from crewai import Agent, Task, Crew

load_dotenv()

# Définir l'agent
chercheur = Agent(
    role="Chercheur en IA",
    goal="Trouver les 3 dernières actualités sur CrewAI",
    backstory=(
        "Tu es un chercheur spécialisé dans l'écosystème des agents IA. "
        "Tu connais parfaitement les outils de la stack open source."
    ),
    verbose=True
)

# Définir la tâche
tache_recherche = Task(
    description="Recherche les 3 dernières nouvelles concernant CrewAI et leur date.",
    expected_output="Une liste de 3 actualités avec titre et date.",
    agent=chercheur
)

# Créer la Crew et lancer
crew = Crew(
    agents=[chercheur],
    tasks=[tache_recherche],
    verbose=True
)

resultat = crew.kickoff()
print("=== Résultat ===")
print(resultat)

Lancer

python agent_simple.py

Sortie attendue :

# Agent: Chercheur en IA
## Task: Recherche les 3 dernières nouvelles concernant CrewAI et leur date.

# Starting Crew Execution
# Agent: Chercheur en IA
## Using LLM: gpt-4o-mini

# [Réponse de l'agent]

# Crew Execution Completed
=== Résultat ===
[Résultat structuré]

Sauvegarder les dépendances

pip freeze > requirements.txt

Pour répliquer l'environnement ailleurs :

pip install -r requirements.txt

---

Dépannage — erreurs courantes

ModuleNotFoundError: No module named 'crewai'

Cause : CrewAI pas installé dans l'environnement actif.

which python  # Vérifie l'environnement
source crewai-env/bin/activate     # Réactiver si nécessaire
pip install crewai

AuthenticationError: Invalid API key

Cause : Clé API absente ou mal chargée.

python -c "import os; print(os.environ.get('OPENAI_API_KEY', 'NON DÉFINIE'))"

Si NON DÉFINIE → ajoutez load_dotenv() en début de script, ou :

export OPENAI_API_KEY=votre-clé-api

ImportError: cannot import name '...' from 'langchain'

Cause : Incompatibilité LangChain / CrewAI.

pip install --upgrade crewai langchain langchain-core

ValueError: Failed to parse JSON output

Cause : Le modèle ne retourne pas du JSON valide.

Solution : Utilisez un modèle stable et temperature=0 :

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)

Lenteur d'exécution

Causes possibles : latence réseau, modèle distant lent, modèle local sous-dimensionné.

Solutions :

• Vérifiez votre connexion Internet
• Passez à gpt-4o-mini (plus rapide que gpt-4o)
• Pour du local : Ollama avec un modèle quantifié (llama3.2:3b)

---

Bonnes pratiques

Verrouillez vos dépendances

pip freeze > requirements.txt

En production, évitez pip install crewai sans version verrouillée. Les mises à jour automatiques peuvent casser la compatibilité.

Un environnement par projet

Ne partagez pas un seul crewai-env entre plusieurs projets. Créez un environnement dédié pour chaque projet.

Structurez dès le départ

mon-projet/
├── agents/
│   ├── __init__.py
│   ├── chercheur.py
│   └── redacteur.py
├── tasks/
│   ├── __init__.py
│   └── definitions.py
├── crew.py
└── main.py

Utilisez Ollama pour les tests

Itérez sans coût API avec un modèle local :

from langchain_ollama import ChatOllama

llm = ChatOllama(model="llama3.2:3b", base_url="http://localhost:11434")

---

FAQ

Quelle version de Python est requise ? Python 3.10 minimum. 3.8 et 3.9 non supportés.

CrewAI est-il gratuit ? Oui, open source. Seuls les appels aux LLMs (OpenAI, Anthropic) engendrent des coûts.

Comment désinstaller ?

source crewai-env/bin/activate
pip uninstall crewai langchain langchain-core
deactivate
rm -rf crewai-env

Peut-on utiliser CrewAI sans OpenAI ? Oui. Anthropic, Google Gemini, Ollama (local), Mistral : installez le package LangChain correspondant.

CrewAI supporte-t-il le multi-agents ? Oui. Voir Créer un agent IA avec CrewAI pour un exemple multi-agents complet.

---

Aller plus loin

Une fois votre agent fonctionnel, explorez :

• Créer un agent IA — rôles, outils et workflows avancés
• Frameworks d'agents IA — comparatif CrewAI, AutoGen, LangGraph, OpenClaw
• Installer OpenClaw sur VPS — déploiement industrialisé
• Agents IA : concepts et architecture
• Automatisation par agents IA