Instalar o SDK de Workflows
Nesta página
Pré-requisitos técnicos
Precisa de quatro elementos antes de escrever a sua primeira linha de código de workflow. Primeiro, precisa do Python 3.12 ou superior, pois os workflows dependem de funcionalidades assíncronas modernas introduzidas nesta versão. O Python 3.11 falhará no momento da importação, e não em tempo de execução, o que pelo menos torna o erro imediato. Segundo, precisa do uv, o gestor de pacotes que a Mistral recomenda para projetos Python. Este gere tanto ambientes virtuais como dependências. Por fim, precisa de uma conta Mistral AI. Crie uma em console.mistral.ai se ainda não o tiver feito e gere uma chave de API na secção “API Keys” da consola.
Verificar a versão do Python
Comece pelo obstáculo mais comum: a versão do interpretador.
python --version
# Deve mostrar Python 3.12.x ou superior
Se a sua versão for inferior à 3.12, atualize o Python antes de continuar. No Ubuntu/Debian:
sudo apt update
sudo apt install python3.12 python3.12-venv
No macOS com Homebrew:
brew install [email protected]
Instalar o uv
Se ainda não tiver o uv, instale-o. O comando difere consoante o 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"
De seguida, verifique se o binário está no seu PATH. Se o comando seguinte devolver “not found”, abra um novo terminal. O instalador modifica o perfil da sua shell:
uv --version
Criar um projeto
Crie um novo projeto Python com o uv:
mkdir mon-workflow-mistral
cd mon-workflow-mistral
uv init
Isto cria um ficheiro pyproject.toml e uma estrutura de projeto padrão. O ficheiro pyproject.toml lista as suas dependências e permite a um colega recriar exatamente o mesmo ambiente.
Instalar o SDK de Workflows
Tem duas opções de instalação e a escolha é importante. Se só precisar do motor de workflows — porque as suas atividades chamam APIs internas, uma base de dados ou serviços de terceiros — a versão básica é suficiente:
uv add mistralai-workflows
Se quiser utilizar agentes duráveis, chamada de ferramentas (tool calling) e transferências entre múltiplos agentes diretamente nos seus workflows, utilize a variante com extras:
uv add "mistralai-workflows[mistralai]"
A segunda opção instala o SDK da Mistral AI como dependência e ativa integrações nativas com os modelos da Mistral. Se não tiver a certeza no início de um projeto, a versão básica é mais leve. Pode adicionar o extra mais tarde sem quebrar nada.
Verificar a instalação
Uma importação bem-sucedida vale mais do que uma longa verificação manual:
uv run python -c "import mistralai.workflows; print('Workflows SDK installed successfully!')"
Deverá ver:
Workflows SDK installed successfully!
Se obtiver um ModuleNotFoundError, não reinstale imediatamente. Primeiro, verifique se está na pasta do projeto onde executou o uv add. O comando uv run resolve o ambiente virtual a partir do diretório atual.
Configurar a sua chave de API
O SDK autentica-se através da variável de ambiente MISTRAL_API_KEY. Lê-a automaticamente; não precisa de a passar como argumento. Defina-a no seu terminal:
# Linux / macOS
export MISTRAL_API_KEY="votre_clé_api_ici"
# Para tornar permanente, adicione-a ao seu ~/.bashrc ou ~/.zshrc
echo export MISTRAL_API_KEY=votre_clé_api_ici >> ~/.bashrc
Este método funciona para desenvolvimento local. Para projetos de produção, prefira um ficheiro .env carregado via python-dotenv ou o gestor de segredos da sua plataforma de implementação. Uma chave num ficheiro .bashrc acabará eventualmente num backup ou numa partilha de ecrã.
Estrutura rápida (opcional)
A Mistral fornece uma ferramenta CLI que gera um projeto de workflow completo. Isto é útil para ver a estrutura esperada antes de escrever a sua própria:
uvx mistralai-workflows-cli setup
O comando produz um ficheiro de workflow de exemplo, um ficheiro de atividade, um worker pronto a iniciar e uma configuração básica. Em segundos, tem um projeto em execução. Pode depois desmontá-lo peça por peça para compreender o papel de cada componente antes de começar do zero.
Estrutura de projeto recomendada
Para um projeto de workflow de produção, recomendamos esta estrutura:
mon-workflow-mistral/
├── pyproject.toml # Dependências (mistralai-workflows)
├── .env # Chave de API (não fazer commit)
├── activities/
│ ├── __init__.py
│ ├── email.py # Atividades relacionadas com e-mail
│ └── data_processing.py # Atividades de processamento de dados
├── workflows/
│ ├── __init__.py
│ └── pipeline.py # Definições de workflow
└── worker.py # Ponto de entrada do worker
Separar as atividades dos workflows facilita a manutenção e os testes unitários. Uma atividade é uma função assíncrona padrão que pode chamar diretamente num teste, enquanto um workflow requer o motor para ser executado. Esta separação leva cinco minutos no início de um projeto e poupa-lhe muito tempo assim que tiver mais de dez atividades.
Pontos-chave
- O Python 3.12+ e o uv são obrigatórios para o SDK de Workflows
- Dois modos de instalação: básico (
mistralai-workflows) ou com integração de IA (mistralai-workflows[mistralai]) - Configure a chave de API através da variável de ambiente
MISTRAL_API_KEY - O comando
uvx mistralai-workflows-cli setupgera um projeto de exemplo completo - Separe as suas atividades, workflows e worker em ficheiros distintos para melhor manutenção