Installare l'SDK Workflows
In questa pagina
Prerequisiti tecnici
Prima di scrivere la tua prima riga di codice per un workflow, devi avere quattro elementi pronti. Innanzitutto, ti serve Python 3.12 o superiore, perché i workflows si basano su funzionalità async moderne introdotte in questa versione. Python 3.11 fallirà al momento dell’importazione, non durante l’esecuzione, il che almeno rende l’errore immediato. In secondo luogo, ti serve uv, il gestore di pacchetti raccomandato da Mistral per i progetti Python. Gestisce sia gli ambienti virtuali che le dipendenze. Infine, ti serve un account Mistral AI. Creane uno su console.mistral.ai se non lo hai già fatto e genera una chiave API nella sezione API Keys della console.
Verifica la versione di Python
Inizia dall’ostacolo più comune: la versione dell’interprete.
python --version
# Deve mostrare Python 3.12.x o superiore
Se la tua versione è inferiore alla 3.12, aggiorna Python prima di continuare. Su Ubuntu/Debian:
sudo apt update
sudo apt install python3.12 python3.12-venv
Su macOS con Homebrew:
brew install [email protected]
Installa uv
Se non hai ancora uv, installalo. Il comando varia a seconda del sistema:
# 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"
Verifica poi che il binario sia nel tuo PATH. Se il comando seguente restituisce “not found”, apri un nuovo terminale. Il programma di installazione modifica il profilo della tua shell:
uv --version
Crea un progetto
Crea un nuovo progetto Python con uv:
mkdir mon-workflow-mistral
cd mon-workflow-mistral
uv init
Questo crea un file pyproject.toml e una struttura di progetto standard. Il file pyproject.toml elenca le tue dipendenze e permette a un collega di ricreare esattamente lo stesso ambiente.
Installa l’SDK Workflows
Hai due opzioni di installazione e la scelta conta. Se ti serve solo il motore di workflow – perché le tue attività chiamano API interne, un database o servizi di terze parti – la versione base è sufficiente:
uv add mistralai-workflows
Se vuoi utilizzare agenti durevoli, chiamate di strumenti (tool calling) e passaggi di consegne tra più agenti direttamente nei tuoi workflows, usa la variante con gli extra:
uv add "mistralai-workflows[mistralai]"
La seconda opzione installa l’SDK Mistral AI come dipendenza e abilita integrazioni native con i modelli Mistral. Se all’inizio di un progetto non sei sicuro, la versione base è più leggera. Puoi aggiungere l’extra in seguito senza rompere nulla.
Verifica l’installazione
Un’importazione riuscita vale più di un lungo controllo manuale:
uv run python -c "import mistralai.workflows; print('Workflows SDK installed successfully!')"
Dovresti vedere:
Workflows SDK installed successfully!
Se ottieni un ModuleNotFoundError, non reinstallare immediatamente. Prima, controlla di essere nella cartella del progetto dove hai eseguito uv add. Il comando uv run risolve l’ambiente virtuale dalla directory corrente.
Configura la tua chiave API
L’SDK si autentica tramite la variabile d’ambiente MISTRAL_API_KEY. La legge automaticamente; non devi passarla come argomento. Impostala nel tuo terminale:
# Linux / macOS
export MISTRAL_API_KEY="votre_clé_api_ici"
# Per renderla permanente, aggiungila al tuo ~/.bashrc o ~/.zshrc
echo export MISTRAL_API_KEY=votre_clé_api_ici >> ~/.bashrc
Questo metodo funziona per lo sviluppo locale. Per i progetti in produzione, preferisci un file .env caricato tramite python-dotenv o il gestore dei segreti della tua piattaforma di deployment. Una chiave in un file .bashrc finirà inevitabilmente in un backup o in una condivisione schermo.
Impalcatura rapida (opzionale)
Mistral fornisce uno strumento CLI che genera un progetto workflow completo. È utile per vedere la struttura attesa prima di scrivere la tua:
uvx mistralai-workflows-cli setup
Il comando produce un file di workflow di esempio, un file di attività, un worker pronto all’avvio e una configurazione di base. In pochi secondi, ottieni un progetto funzionante. Puoi poi smontarlo pezzo per pezzo per capire il ruolo di ogni componente prima di partire da zero.
Struttura del progetto consigliata
Per un progetto workflow in produzione, consigliamo questa struttura:
mon-workflow-mistral/
├── pyproject.toml # Dipendenze (mistralai-workflows)
├── .env # Chiave API (non fare commit)
├── activities/
│ ├── __init__.py
│ ├── email.py # Attività relative alle email
│ └── data_processing.py # Attività di elaborazione dati
├── workflows/
│ ├── __init__.py
│ └── pipeline.py # Definizioni dei workflow
└── worker.py # Punto di ingresso del worker
Separare le attività dai workflows rende la manutenzione e i test unitari più semplici. Un’attività è una funzione async standard che puoi chiamare direttamente in un test, mentre un workflow richiede il motore per essere eseguito. Questa separazione richiede cinque minuti all’inizio di un progetto e ti fa risparmiare molto tempo una volta superate le dieci attività.
Punti chiave
- Python 3.12+ e uv sono richiesti per l’SDK Workflows
- Due modalità di installazione: base (
mistralai-workflows) o con integrazione AI (mistralai-workflows[mistralai]) - Configura la chiave API tramite la variabile d’ambiente
MISTRAL_API_KEY - Il comando
uvx mistralai-workflows-cli setupgenera un progetto di esempio completo - Separa le tue attività, i workflow e il worker in file distinti per una migliore manutenibilità