Installation des Workflows-SDK

Technische Voraussetzungen

Bevor Sie die erste Zeile Workflow-Code schreiben, müssen vier Dinge bereitgestellt sein. Erstens benötigen Sie Python 3.12 oder höher, da Workflows auf modernen asynchronen Funktionen angewiesen sind, die in dieser Version eingeführt wurden. Python 3.11 führt zu Fehlern beim Import, nicht zur Laufzeit, was den Fehler zumindest sofort sichtbar macht. Zweitens benötigen Sie uv, den Paketmanager, den Mistral für Python-Projekte empfiehlt. Er verwaltet sowohl virtuelle Umgebungen als auch Abhängigkeiten. Drittens benötigen Sie ein Mistral AI-Konto. Erstellen Sie eines unter console.mistral.ai, falls Sie noch keines haben, und generieren Sie einen API-Schlüssel im Bereich API-Schlüssel der Konsole.

Überprüfung Ihrer Python-Version

Beginnen Sie mit dem häufigsten Hindernis: der Interpret-Version.

python --version
# Muss Python 3.12.x oder höher anzeigen

Falls Ihre Version niedriger als 3.12 ist, aktualisieren Sie Python, bevor Sie fortfahren. Auf Ubuntu/Debian:

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

Auf macOS mit Homebrew:

brew install [email protected]

Installation von uv

Falls Sie uv noch nicht haben, installieren Sie es. Der Befehl variiert je nach System:

# 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"

Überprüfen Sie anschließend, ob die Binärdatei in Ihrem PATH liegt. Wenn der folgende Befehl „nicht gefunden” zurückgibt, öffnen Sie ein neues Terminal. Der Installer modifiziert Ihr Shell-Profil:

uv --version

Erstellung eines Projekts

Erstellen Sie ein neues Python-Projekt mit uv:

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

Dies erstellt eine pyproject.toml-Datei und eine standardmäßige Projektstruktur. Die pyproject.toml-Datei listet Ihre Abhängigkeiten auf und ermöglicht es einem Kollegen, die exakte gleiche Umgebung nachzubauen.

Sie haben zwei Installationsmöglichkeiten, und die Wahl ist entscheidend. Wenn Sie nur den Workflow-Engine benötigen – weil Ihre Aktivitäten interne APIs, eine Datenbank oder Drittanbieterdienste aufrufen – reicht die Basisversion aus:

uv add mistralai-workflows

Wenn Sie durable Agents, Tool-Calling und Multi-Agent-Handovers direkt in Ihren Workflows nutzen möchten, verwenden Sie die Variante mit Extras:

uv add "mistralai-workflows[mistralai]"

Die zweite Option installiert das Mistral AI SDK als Abhängigkeit und ermöglicht native Integrationen mit Mistral-Modellen. Wenn Sie am Anfang eines Projekts unsicher sind, ist die Basisversion leichter. Sie können das Extra später hinzufügen, ohne etwas zu brechen.

Überprüfung der Installation

Ein erfolgreicher Import schlägt eine lange manuelle Prüfung:

uv run python -c "import mistralai.workflows; print('Workflows SDK installed successfully!')"

Sie sollten sehen:

Workflows SDK installed successfully!

Wenn Sie einen ModuleNotFoundError erhalten, installieren Sie nicht sofort neu. Überprüfen Sie zunächst, ob Sie sich im Projektordner befinden, in dem Sie uv add ausgeführt haben. Der Befehl uv run löst die virtuelle Umgebung aus dem aktuellen Verzeichnis.

Konfiguration Ihres API-Schlüssels

Das SDK authentifiziert sich über die Umgebungsvariable MISTRAL_API_KEY. Diese wird automatisch gelesen; Sie müssen sie nicht als Argument übergeben. Setzen Sie sie in Ihrem Terminal:

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

# Um sie dauerhaft zu machen, fügen Sie sie zu Ihrem ~/.bashrc oder ~/.zshrc hinzu
echo export MISTRAL_API_KEY=votre_clé_api_ici >> ~/.bashrc

Diese Methode funktioniert für die lokale Entwicklung. Für Produktionsprojekte bevorzugen Sie eine .env-Datei, die über python-dotenv geladen wird, oder den Secrets Manager Ihrer Bereitstellungsplattform. Ein Schlüssel in einer .bashrc-Datei landet am Ende in einem Backup oder einem Bildschirmfreigabe.

Schnelle Gerüst-Erstellung (optional)

Mistral stellt ein CLI-Tool bereit, das ein vollständiges Workflow-Projekt generiert. Dies ist nützlich, um die erwartete Struktur zu sehen, bevor Sie Ihren eigenen Code schreiben:

uvx mistralai-workflows-cli setup

Der Befehl erzeugt eine Beispiel-Workflow-Datei, eine Aktivitätsdatei, einen sofort einsatzbereiten Worker und eine grundlegende Konfiguration. In Sekunden haben Sie ein laufendes Projekt. Sie können es dann Stück für Stück zerlegen, um die Rolle jedes Komponenten zu verstehen, bevor Sie von Grund auf neu beginnen.

Empfohlene Projektstruktur

Für ein Produktions-Workflow-Projekt empfehlen wir folgende Struktur:

mon-workflow-mistral/
├── pyproject.toml          # Abhängigkeiten (mistralai-workflows)
├── .env                    # API-Schlüssel (nicht committen)
├── activities/
│   ├── __init__.py
│   ├── email.py            # E-Mail-bezogene Aktivitäten
│   └── data_processing.py  # Datenverarbeitungs-Aktivitäten
├── workflows/
│   ├── __init__.py
│   └── pipeline.py         # Workflow-Definitionen
└── worker.py               # Worker-Einstiegspunkt

Die Trennung von Aktivitäten und Workflows erleichtert Wartung und Unit-Tests. Eine Aktivität ist eine standardmäßige asynchrone Funktion, die Sie direkt in einem Test aufrufen können, während ein Workflow den Engine benötigt, um ausgeführt zu werden. Diese Trennung kostet am Anfang eines Projekts fünf Minuten und spart Ihnen später viel Zeit, sobald Sie mehr als zehn Aktivitäten haben.

Kernaussagen

Python 3.12+ und uv sind für das Workflows-SDK erforderlich
Zwei Installationsmodi: Basis (mistralai-workflows) oder mit KI-Integration (mistralai-workflows[mistralai])
Konfigurieren Sie den API-Schlüssel über die Umgebungsvariable MISTRAL_API_KEY
Der Befehl uvx mistralai-workflows-cli setup generiert ein vollständiges Beispielprojekt
Trennen Sie Ihre Aktivitäten, Workflows und den Worker in separate Dateien für bessere Wartbarkeit