Instalace Workflows SDK
Na této stránce
Technické předpoklady
Než napíšeš první řádek kódu pro workflow, musíš mít připravené čtyři věci. Zaprvé potřebuješ Python 3.12 nebo vyšší, protože workflow využívají moderní asynchronní funkce zavedené v této verzi. Python 3.11 selže již při importu, nikoliv až za běhu, což alespoň znamená, že chyba vyskočí okamžitě. Zadruhé potřebuješ uv, správce balíčků, který Mistral pro Python projekty doporučuje. Stará se jak o virtuální prostředí, tak o závislosti. Nakonec potřebuješ účet Mistral AI. Pokud ho ještě nemáš, založ si ho na console.mistral.ai a v sekci API Keys v konzoli vygeneruj API klíč.
Kontrola verze Pythonu
Začni tím nejčastějším úskalím: verzí interpretu.
python --version
# Musí zobrazit Python 3.12.x nebo vyšší
Pokud máš verzi nižší než 3.12, aktualizuj Python před pokračováním. Na Ubuntu/Debian:
sudo apt update
sudo apt install python3.12 python3.12-venv
Na macOS s Homebrew:
brew install [email protected]
Instalace uv
Pokud ještě nemáš uv, nainstaluj si ho. Příkaz se liší podle systému:
# 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"
Poté ověř, že je binární soubor v tvém PATH. Pokud následující příkaz vrátí „not found“, otevři nový terminál. Instalátor upraví profil tvého shellu:
uv --version
Vytvoření projektu
Vytvoř nový Python projekt pomocí uv:
mkdir mon-workflow-mistral
cd mon-workflow-mistral
uv init
Tím se vytvoří soubor pyproject.toml a standardní struktura projektu. Soubor pyproject.toml obsahuje seznam závislostí a umožňuje kolegovi recreate přesně stejné prostředí.
Instalace Workflows SDK
Máš dvě možnosti instalace a na výběru záleží. Pokud potřebuješ pouze engine pro workflow – protože tvé aktivity volají interní API, databázi nebo služby třetích stran – stačí základní verze:
uv add mistralai-workflows
Pokud chceš ve svých workflow přímo využívat odolné agenty (durable agents), volání nástrojů a předávání úloh mezi více agenty, použij variantu s extra balíčky:
uv add "mistralai-workflows[mistralai]"
Druhá možnost nainstaluje Mistral AI SDK jako závislost a umožní nativní integraci s modely Mistral. Pokud si na začátku projektu nejsi jistý, základní verze je lehčí. Extra balíček můžeš přidat později, aniž bys něco rozbil.
Ověření instalace
Úspěšný import nahradí zdlouhavou ruční kontrolu:
uv run python -c "import mistralai.workflows; print('Workflows SDK installed successfully!')"
Měl bys vidět:
Workflows SDK installed successfully!
Pokud dostaneš chybu ModuleNotFoundError, nepřeinstalovávej hned. Nejprve zkontroluj, zda jsi ve složce projektu, kde jsi spustil uv add. Příkaz uv run řeší virtuální prostředí z aktuálního adresáře.
Konfigurace API klíče
SDK se autentizuje prostřednictvím proměnné prostředí MISTRAL_API_KEY. Načte ji automaticky; nemusíš ji předávat jako argument. Nastav ji v terminálu:
# Linux / macOS
export MISTRAL_API_KEY="votre_clé_api_ici"
# Pro trvalé nastavení ji přidej do ~/.bashrc nebo ~/.zshrc
echo export MISTRAL_API_KEY=votre_clé_api_ici >> ~/.bashrc
Tato metoda funguje pro lokální vývoj. U produkčních projektů upřednostni soubor .env načítaný přes python-dotenv nebo správce tajných klíčů tvé nasazovací platformy. Klíč v souboru .bashrc se dříve či později dostane do zálohy nebo na sdílenou obrazovku.
Rychlá kostra projektu (volitelné)
Mistral poskytuje nástroj CLI, který vygeneruje kompletní projekt workflow. To je užitečné pro pochopení očekávané struktury před tím, než začneš psát vlastní kód:
uvx mistralai-workflows-cli setup
Příkaz vytvoří ukázkový soubor workflow, soubor aktivit, pracovníka připraveného ke spuštění a základní konfiguraci. Během několika vteřin máš běžící projekt. Poté ho můžeš rozebrat část po části, abys pochopil roli každé komponenty, než začneš od nuly.
Doporučená struktura projektu
Pro produkční projekt workflow doporučujeme tuto strukturu:
mon-workflow-mistral/
├── pyproject.toml # Závislosti (mistralai-workflows)
├── .env # API klíč (nekomitovat)
├── activities/
│ ├── __init__.py
│ ├── email.py # Aktivity související s e-maily
│ └── data_processing.py # Aktivity pro zpracování dat
├── workflows/
│ ├── __init__.py
│ └── pipeline.py # Definice workflow
└── worker.py # Vstupní bod pracovníka
Oddělení aktivit od workflow usnadňuje údržbu a unit testování. Aktivita je standardní asynchronní funkce, kterou můžeš přímo zavolat v testu, zatímco workflow vyžaduje ke spuštění engine. Toto oddělení zabere na začátku projektu pět minut, ale ušetří ti spoustu času, jakmile budeš mít více než deset aktivit.
Klíčové poznatky
- Pro Workflows SDK jsou vyžadovány Python 3.12+ a uv
- Dva režimy instalace: základní (
mistralai-workflows) nebo s AI integrací (mistralai-workflows[mistralai]) - API klíč nakonfiguruj prostřednictvím proměnné prostředí
MISTRAL_API_KEY - Příkaz
uvx mistralai-workflows-cli setupvygeneruje kompletní ukázkový projekt - Pro lepší udržovatelnost odděl aktivity, workflow a pracovníka do samostatných souborů