Installer le SDK Workflows

Prérequis techniques

Avant de commencer à écrire vos premiers workflows, vous devez disposer de l’environnement suivant :

Python 3.12 ou supérieur — Les workflows utilisent des fonctionnalités async modernes qui nécessitent Python 3.12+
uv — Le gestionnaire de paquets recommandé par Mistral pour les projets Python
Un compte Mistral AI — Créez-le sur console.mistral.ai si ce n’est pas déjà fait
Une clé API — Générez-la depuis la console Mistral dans la section API Keys

Vérifier votre version de Python

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 :

# 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 l’installation :

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.

Installation basique

Pour utiliser uniquement le moteur de workflows :

uv add mistralai-workflows

Installation avec intégration Mistral AI

Si vous souhaitez utiliser les agents durables, le tool calling et les handoffs multi-agents directement dans vos workflows :

uv add "mistralai-workflows[mistralai]"

Cette variante installe le SDK Mistral AI en dépendance et active les intégrations natives avec les modèles Mistral.

Vérifier l’installation

Lancez cette commande pour confirmer que tout est correctement installé :

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, vérifiez que vous êtes bien dans le dossier du projet où uv add a été exécuté.

Configurer votre clé API

Le SDK utilise la variable d’environnement MISTRAL_API_KEY pour s’authentifier. 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

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.

Scaffolding rapide (optionnel)

Mistral fournit un outil CLI pour générer un projet de workflow complet :

uvx mistralai-workflows-cli setup

Cette commande crée automatiquement :

Un fichier de workflow d’exemple
Un fichier d’activité
Un worker prêt à démarrer
La configuration de base

C’est un bon point de départ pour explorer la structure avant de créer vos propres workflows.

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.

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é