Ir al contenido principal
Español— Elegir un idioma
Menú

Instalación del SDK de Workflows

Lección 3 de 14 Actualizado el 29 de julio de 2026 Avanzado
En esta página
  1. Requisitos técnicos previos
  2. Comprueba tu versión de Python
  3. Instala uv
  4. Crea un proyecto
  5. Instala el SDK de Workflows
  6. Verifica la instalación
  7. Configura tu clave de API
  8. Andamiaje rápido (opcional)
  9. Estructura de proyecto recomendada
  10. Puntos clave

Requisitos técnicos previos

Antes de escribir la primera línea de código de un workflow, necesitas tener cuatro elementos listos. En primer lugar, necesitas Python 3.12 o superior, ya que los workflows dependen de funciones asíncronas modernas introducidas en esta versión. Python 3.11 fallará en el momento de la importación, no en tiempo de ejecución, lo que al menos hace que el error sea inmediato. En segundo lugar, necesitas uv, el gestor de paquetes que Mistral recomienda para proyectos Python. Se encarga tanto de los entornos virtuales como de las dependencias. Por último, necesitas una cuenta de Mistral AI. Crea una en console.mistral.ai si aún no la tienes y genera una clave de API en la sección API Keys de la consola.

Comprueba tu versión de Python

Empieza por el obstáculo más común: la versión del intérprete.

python --version
# Debe mostrar Python 3.12.x o superior

Si tu versión es inferior a la 3.12, actualiza Python antes de continuar. En Ubuntu/Debian:

sudo apt update
sudo apt install python3.12 python3.12-venv

En macOS con Homebrew:

brew install [email protected]

Instala uv

Si aún no tienes uv, instálalo. El comando varía según el 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"

A continuación, verifica que el binario esté en tu PATH. Si el siguiente comando devuelve “not found”, abre un nuevo terminal. El instalador modifica el perfil de tu shell:

uv --version

Crea un proyecto

Crea un nuevo proyecto Python con uv:

mkdir mon-workflow-mistral
cd mon-workflow-mistral
uv init

Esto crea un archivo pyproject.toml y una estructura de proyecto estándar. El archivo pyproject.toml enumera tus dependencias y permite a un colega recrear exactamente el mismo entorno.

Instala el SDK de Workflows

Tienes dos opciones de instalación y la elección importa. Si solo necesitas el motor de workflows —porque tus actividades llaman a APIs internas, a una base de datos o a servicios de terceros—, la versión básica es suficiente:

uv add mistralai-workflows

Si quieres usar agentes duraderos, llamadas a herramientas (tool calling) y transferencias entre múltiples agentes directamente en tus workflows, usa la variante con extras:

uv add "mistralai-workflows[mistralai]"

La segunda opción instala el SDK de Mistral AI como dependencia y habilita integraciones nativas con los modelos de Mistral. Si no estás seguro al inicio de un proyecto, la versión básica es más ligera. Puedes añadir el extra más tarde sin romper nada.

Verifica la instalación

Una importación exitosa vale más que una larga comprobación manual:

uv run python -c "import mistralai.workflows; print('Workflows SDK installed successfully!')"

Deberías ver:

Workflows SDK installed successfully!

Si obtienes un ModuleNotFoundError, no reinstales inmediatamente. Primero, comprueba que estás en la carpeta del proyecto donde ejecutaste uv add. El comando uv run resuelve el entorno virtual desde el directorio actual.

Configura tu clave de API

El SDK se autentica mediante la variable de entorno MISTRAL_API_KEY. La lee automáticamente; no necesitas pasarla como argumento. Establécela en tu terminal:

# Linux / macOS
export MISTRAL_API_KEY="votre_clé_api_ici"

# Para hacerla permanente, añádela a tu ~/.bashrc o ~/.zshrc
echo export MISTRAL_API_KEY=votre_clé_api_ici >> ~/.bashrc

Este método funciona para el desarrollo local. Para proyectos de producción, es preferible un archivo .env cargado mediante python-dotenv o el gestor de secretos de tu plataforma de despliegue. Una clave en un archivo .bashrc acabará posiblemente en una copia de seguridad o en una compartición de pantalla.

Andamiaje rápido (opcional)

Mistral proporciona una herramienta CLI que genera un proyecto de workflow completo. Esto es útil para ver la estructura esperada antes de escribir la tuya propia:

uvx mistralai-workflows-cli setup

El comando produce un archivo de workflow de ejemplo, un archivo de actividades, un worker listo para iniciar y una configuración básica. En segundos, tienes un proyecto en funcionamiento. Puedes desmontarlo pieza a pieza para entender el papel de cada componente antes de empezar desde cero.

Estructura de proyecto recomendada

Para un proyecto de workflow de producción, recomendamos esta estructura:

mon-workflow-mistral/
├── pyproject.toml          # Dependencias (mistralai-workflows)
├── .env                    # Clave de API (no hacer commit)
├── activities/
│   ├── __init__.py
│   ├── email.py            # Actividades relacionadas con correo
│   └── data_processing.py  # Actividades de procesamiento de datos
├── workflows/
│   ├── __init__.py
│   └── pipeline.py         # Definiciones de workflows
└── worker.py               # Punto de entrada del worker

Separar las actividades de los workflows facilita el mantenimiento y las pruebas unitarias. Una actividad es una función asíncrona estándar que puedes llamar directamente en una prueba, mientras que un workflow requiere el motor para ejecutarse. Esta separación lleva cinco minutos al inicio de un proyecto y te ahorra mucho tiempo una vez que tienes más de diez actividades.

Puntos clave

  • Python 3.12+ y uv son necesarios para el SDK de Workflows
  • Dos modos de instalación: básico (mistralai-workflows) o con integración de IA (mistralai-workflows[mistralai])
  • Configura la clave de API mediante la variable de entorno MISTRAL_API_KEY
  • El comando uvx mistralai-workflows-cli setup genera un proyecto de ejemplo completo
  • Separa tus actividades, workflows y worker en archivos distintos para mejorar la mantenibilidad