Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Instalar o SDK de Workflows

Aula 3 de 14 Atualizada a 29 de julho de 2026 Avancado
Nesta página
  1. Pré-requisitos técnicos
  2. Verificar a versão do Python
  3. Instalar o uv
  4. Criar um projeto
  5. Instalar o SDK de Workflows
  6. Verificar a instalação
  7. Configurar a sua chave de API
  8. Estrutura rápida (opcional)
  9. Estrutura de projeto recomendada
  10. Pontos-chave

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 setup gera um projeto de exemplo completo
  • Separe as suas atividades, workflows e worker em ficheiros distintos para melhor manutenção