Installer le SDK Workflows

Prérequis techniques

Quatre éléments doivent être réunis avant d’écrire votre première ligne de workflow. Il vous faut Python 3.12 ou supérieur, parce que les workflows s’appuient sur des fonctionnalités async modernes introduites dans cette version — une 3.11 échouera à l’import, pas à l’exécution, ce qui rend l’erreur heureusement immédiate. Il vous faut ensuite uv, le gestionnaire de paquets recommandé par Mistral pour les projets Python, qui gère à la fois l’environnement virtuel et les dépendances. Il vous faut enfin un compte Mistral AI, à créer sur console.mistral.ai si ce n’est pas déjà fait, et une clé API générée depuis la console dans la section API Keys.

Vérifier votre version de Python

Commencez par le point qui bloque le plus souvent, la version de l’interpréteur :

python --version
# Doit afficher Python 3.12.x ou supérieur

Si votre version est inférieure à 3.12, mettez à jour Python avant de continuer. Sur Ubuntu/Debian :

sudo apt update
sudo apt install python3.12 python3.12-venv

Sur macOS avec Homebrew :

brew install [email protected]

Installer uv

Si vous n’avez pas encore uv, installez-le. La commande diffère selon votre système :

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

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Vérifiez ensuite que le binaire est bien dans votre PATH — si la commande suivante reste introuvable, ouvrez un nouveau terminal, l’installateur modifie le profil du shell :

uv --version

Créer un projet

Créez un nouveau projet Python avec uv :

mkdir mon-workflow-mistral
cd mon-workflow-mistral
uv init

Cela crée un fichier pyproject.toml et une structure de projet standard. C’est ce pyproject.toml qui recensera vos dépendances et permettra à un collègue de reconstituer exactement le même environnement.

Deux installations sont possibles, et le choix n’est pas anodin. Si vous n’avez besoin que du moteur de workflows — parce que vos activités appellent des API maison, une base de données ou des services tiers — la version basique suffit :

uv add mistralai-workflows

Si en revanche vous souhaitez utiliser les agents durables, le tool calling et les handoffs multi-agents directement dans vos workflows, prenez la variante avec extra :

uv add "mistralai-workflows[mistralai]"

Cette seconde forme installe le SDK Mistral AI en dépendance et active les intégrations natives avec les modèles Mistral. En cas de doute au démarrage d’un projet, la version basique reste plus légère et l’extra s’ajoute plus tard sans rien casser.

Vérifier l’installation

Un import réussi vaut mieux qu’une longue vérification manuelle :

uv run python -c "import mistralai.workflows; print('SDK Workflows installé avec succès !')"

Vous devez voir s’afficher :

SDK Workflows installé avec succès !

Si vous obtenez une erreur ModuleNotFoundError, ne réinstallez pas immédiatement : vérifiez d’abord que vous êtes bien dans le dossier du projet où uv add a été exécuté, car uv run résout l’environnement virtuel à partir du répertoire courant.

Configurer votre clé API

Le SDK s’authentifie via la variable d’environnement MISTRAL_API_KEY, qu’il lit tout seul sans que vous ayez à la passer en argument. Configurez-la dans votre terminal :

# Linux / macOS
export MISTRAL_API_KEY="votre_clé_api_ici"

# Pour la rendre permanente, ajoutez-la à votre ~/.bashrc ou ~/.zshrc
echo export MISTRAL_API_KEY=votre_clé_api_ici >> ~/.bashrc

Cette méthode convient au développement local. Pour un projet en production, privilégiez un fichier .env avec un chargement via python-dotenv ou les secrets de votre plateforme de déploiement — une clé dans un .bashrc finit tôt ou tard dans une sauvegarde ou un partage d’écran.

Scaffolding rapide (optionnel)

Mistral fournit un outil CLI qui génère un projet de workflow complet, utile pour voir la structure attendue avant d’écrire la vôtre :

uvx mistralai-workflows-cli setup

La commande produit un fichier de workflow d’exemple, un fichier d’activité, un worker prêt à démarrer et la configuration de base. Vous obtenez ainsi en quelques secondes un projet qui tourne, que vous pouvez démonter pièce par pièce pour comprendre le rôle de chacune avant de partir de zéro.

Structure recommandée d’un projet

Pour un projet de workflows en production, voici la structure recommandée :

mon-workflow-mistral/
├── pyproject.toml          # Dépendances (mistralai-workflows)
├── .env                    # Clé API (ne pas commiter)
├── activities/
│   ├── __init__.py
│   ├── email.py            # Activités liées aux emails
│   └── data_processing.py  # Activités de traitement de données
├── workflows/
│   ├── __init__.py
│   └── pipeline.py         # Définitions des workflows
└── worker.py               # Point d'entrée du worker

Séparer les activités des workflows facilite la maintenance et le test unitaire de chaque composant : une activité est une fonction async ordinaire que vous pouvez appeler directement dans un test, alors qu’un workflow demande le moteur pour s’exécuter. Cette séparation prend cinq minutes au début du projet et vous en fait gagner beaucoup lorsque le nombre d’activités dépasse la dizaine.

Points clés à retenir

Python 3.12+ et uv sont requis pour le SDK Workflows
Deux modes d’installation : basique (mistralai-workflows) ou avec intégration IA (mistralai-workflows[mistralai])
La clé API se configure via la variable d’environnement MISTRAL_API_KEY
La commande uvx mistralai-workflows-cli setup génère un projet d’exemple complet
Séparez vos activités, workflows et worker dans des fichiers distincts pour une meilleure maintenabilité