Installeer de Workflows SDK
Op deze pagina
Technische vereisten
Voordat u uw eerste regel workflow-code schrijft, moeten vier zaken in orde zijn. Ten eerste heeft u Python 3.12 of hoger nodig, omdat workflows afhankelijk zijn van moderne async-functies die in deze versie zijn geïntroduceerd. Python 3.11 zal falen tijdens het importeren, niet tijdens de runtime, wat de fout in ieder geval direct zichtbaar maakt. Ten tweede heeft u uv nodig, de package manager die Mistral aanbeveelt voor Python-projecten. Deze tool beheert zowel virtuele omgevingen als afhankelijkheden. Tot slot heeft u een Mistral AI-account nodig. Maak er een aan op console.mistral.ai als u dat nog niet heeft gedaan, en genereer een API-sleutel in het gedeelte API Keys van de console.
Controleer uw Python-versie
Begin met de meest voorkomende struikelblok: de versie van de interpreter.
python --version
# Moet Python 3.12.x of hoger weergeven
Als uw versie lager is dan 3.12, update Python dan voordat u verdergaat. Op Ubuntu/Debian:
sudo apt update
sudo apt install python3.12 python3.12-venv
Op macOS met Homebrew:
brew install [email protected]
Installeer uv
Als u uv nog niet heeft, installeer het dan. Het commando verschilt per systeem:
# 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"
Verifieer vervolgens of het binary-bestand in uw PATH staat. Als het volgende commando “not found” retourneert, opent u een nieuwe terminal. Het installatieprogramma wijzigt uw shell-profiel:
uv --version
Maak een project aan
Maak een nieuw Python-project aan met uv:
mkdir mon-workflow-mistral
cd mon-workflow-mistral
uv init
Dit creëert een pyproject.toml-bestand en een standaard projectstructuur. Het pyproject.toml-bestand vermeldt uw afhankelijkheden en stelt een collega in staat om exact dezelfde omgeving te reproduceren.
Installeer de Workflows SDK
U heeft twee installatieopties en de keuze is belangrijk. Als u alleen de workflow-engine nodig heeft—omdat uw activiteiten interne API’s, een database of diensten van derden aanroepen—dan volstaat de basisversie:
uv add mistralai-workflows
Als u duurzame agents, tool calling en multi-agent overdrachten direct in uw workflows wilt gebruiken, kies dan voor de variant met extra’s:
uv add "mistralai-workflows[mistralai]"
De tweede optie installeert de Mistral AI SDK als afhankelijkheid en schakelt native integraties met Mistral-modellen in. Als u aan het begin van een project twijfelt, is de basisversie lichter. U kunt de extra’s later toevoegen zonder iets te breken.
Verifieer de installatie
Een succesvolle import weegt zwaarder dan een lange handmatige controle:
uv run python -c "import mistralai.workflows; print('Workflows SDK installed successfully!')"
U zou het volgende moeten zien:
Workflows SDK installed successfully!
Als u een ModuleNotFoundError krijgt, herinstalleer dan niet onmiddellijk. Controleer eerst of u zich in de projectmap bevindt waar u uv add heeft uitgevoerd. Het commando uv run lost de virtuele omgeving op vanuit de huidige map.
Configureer uw API-sleutel
De SDK verifieert via de omgevingsvariabele MISTRAL_API_KEY. Deze wordt automatisch gelezen; u hoeft deze niet als argument door te geven. Stel deze in uw terminal in:
# Linux / macOS
export MISTRAL_API_KEY="votre_clé_api_ici"
# Om dit permanent te maken, voegt u het toe aan uw ~/.bashrc of ~/.zshrc
echo export MISTRAL_API_KEY=votre_clé_api_ici >> ~/.bashrc
Deze methode werkt voor lokale ontwikkeling. Voor productieprojecten geeft u de voorkeur aan een .env-bestand dat wordt geladen via python-dotenv of via de secrets manager van uw deployplatform. Een sleutel in een .bashrc-bestand belandt uiteindelijk toch wel in een back-up of tijdens een schermdeelssessie.
Snelle scaffolding (optioneel)
Mistral biedt een CLI-tool die een compleet workflow-project genereert. Dit is nuttig om de verwachte structuur te zien voordat u zelf begint te schrijven:
uvx mistralai-workflows-cli setup
Het commando produceert een voorbeeld workflow-bestand, een activity-bestand, een startklare worker en een basisconfiguratie. Binnen enkele seconden heeft u een werkend project. U kunt het vervolgens stuk voor stuk uit elkaar halen om de rol van elke component te begrijpen voordat u helemaal vanaf nul begint.
Aanbevolen projectstructuur
Voor een productie workflow-project raden wij deze structuur aan:
mon-workflow-mistral/
├── pyproject.toml # Afhankelijkheden (mistralai-workflows)
├── .env # API-sleutel (niet committen)
├── activities/
│ ├── __init__.py
│ ├── email.py # E-mail gerelateerde activiteiten
│ └── data_processing.py # Gegevensverwerkingsactiviteiten
├── workflows/
│ ├── __init__.py
│ └── pipeline.py # Workflow definities
└── worker.py # Worker entry point
Het scheiden van activiteiten van workflows maakt onderhoud en unit-testen eenvoudiger. Een activiteit is een standaard async-functie die u direct in een test kunt aanroepen, terwijl een workflow de engine nodig heeft om te draaien. Deze scheiding kost vijf minuten aan het begin van een project en bespaart u veel tijd zodra u meer dan tien activiteiten heeft.
Belangrijkste punten
- Python 3.12+ en uv zijn vereist voor de Workflows SDK
- Twee installatiemodi: basis (
mistralai-workflows) of met AI-integratie (mistralai-workflows[mistralai]) - Configureer de API-sleutel via de omgevingsvariabele
MISTRAL_API_KEY - Het commando
uvx mistralai-workflows-cli setupgenereert een compleet voorbeeldproject - Splits uw activiteiten, workflows en worker in afzonderlijke bestanden voor beter onderhoud