Crear un worker
En esta página
La función del worker
El worker es el proceso de Python que ejecuta realmente tus flujos de trabajo y actividades. Se conecta a la plataforma de Mistral, escucha las tareas pendientes y las ejecuta localmente en tu máquina o servidor. Este detalle arquitectónico suele sorprender a los recién llegados: tu código nunca sale de tu entorno; solo el estado de la orquestación reside en Mistral.
La implicación es directa y explica la mayoría de los problemas de «no ocurre nada» que surgen al inicio de un proyecto: sin un worker en ejecución, tus flujos de trabajo no pueden ejecutarse. Puedes desencadenar una ejecución, pero esta simplemente esperará hasta que aparezca un worker capaz de procesarla. El worker es el enlace entre la plataforma de orquestación de Mistral y tu código local.
Crear un worker mínimo
Un worker funcional cabe en pocas líneas. El ejemplo siguiente combina intencionadamente la actividad, el flujo de trabajo y la lógica de inicio en un único archivo para que puedas ejecutarlo de inmediato:
import asyncio
import mistralai.workflows as workflows
# Importa tus flujos de trabajo y actividades
@workflows.activity()
async def dire_bonjour(nom: str) -> dict:
return {"message": f"Bonjour, {nom} !"}
@workflows.workflow.define(name="salutation_workflow")
class SalutationWorkflow:
@workflows.workflow.entrypoint
async def run(self, nom: str) -> dict:
resultat = await dire_bonjour(nom)
return resultat
# Inicia el worker
async def main() -> None:
await workflows.run_worker([SalutationWorkflow])
if __name__ == "__main__":
asyncio.run(main())
La función clave es workflows.run_worker(). Recibe una lista de clases de flujo de trabajo que este worker puede ejecutar, y solo flujos de trabajo. Las actividades se descubren a través de ellos, por lo que no necesitas listar las actividades por separado.
Qué hace run_worker()
Cuando llamas a workflows.run_worker([MyWorkflow]), ocurren cinco cosas en secuencia. Primero, el worker se autentica con la plataforma de Mistral usando tu clave de API. A continuación, registra los flujos de trabajo y actividades declarados. Este registro informa a la plataforma de que existe un ejecutor para el identificador salutation_workflow. Después, abre una conexión persistente y espera tareas, permaneciendo intencionadamente inactivo hasta que se desencadena una ejecución. Cuando llega una ejecución, el worker ejecuta el código localmente y los resultados se envían de vuelta a la plataforma para su persistencia.
El worker permanece activo mientras el proceso de Python esté en ejecución, razón por la cual nunca devuelve el control a tu terminal. Usa Ctrl+C para detenerlo limpiamente.
Worker con múltiples flujos de trabajo
Nada exige un worker por flujo de trabajo. Un único proceso puede alojar múltiples flujos de trabajo, incluso cuando comparten actividades. Aquí, extraire_texte y analyser_sentiment sirven a ambos:
import asyncio
import mistralai.workflows as workflows
# --- Actividades ---
@workflows.activity()
async def extraire_texte(url: str) -> dict:
async with httpx.AsyncClient() as client:
response = await client.get(url)
return {"texte": response.text}
@workflows.activity()
async def analyser_sentiment(texte: str) -> dict:
client = Mistral()
response = await client.chat.complete_async(
model="mistral-large-latest",
messages=[
{"role": "system", "content": "Analysez le sentiment : positif, négatif ou neutre."},
{"role": "user", "content": texte}
]
)
return {"sentiment": response.choices[0].message.content}
@workflows.activity()
async def envoyer_alerte(message: str) -> dict:
# Envío a Slack, correo electrónico, etc.
return {"status": "envoyé"}
# --- Flujos de trabajo ---
@workflows.workflow.define(name="analyse_document")
class DocumentAnalysis:
@workflows.workflow.entrypoint
async def run(self, url: str) -> dict:
extraction = await extraire_texte(url)
sentiment = await analyser_sentiment(extraction["texte"])
return sentiment
@workflows.workflow.define(name="surveillance_mentions")
class MentionMonitoring:
@workflows.workflow.entrypoint
async def run(self, url: str, seuil: str) -> dict:
extraction = await extraire_texte(url)
sentiment = await analyser_sentiment(extraction["texte"])
if sentiment["sentiment"] == "négatif":
await envoyer_alerte(f"Mention négative détectée : {url}")
return sentiment
# --- Worker ---
async def main() -> None:
await workflows.run_worker([
DocumentAnalysis,
MentionMonitoring,
])
if __name__ == "__main__":
asyncio.run(main())
Estructura de archivos recomendada
Un único archivo funciona para el aprendizaje, pero no para un proyecto en producción. Para entornos productivos, separa tu código en módulos por tipo:
mon-projet/
├── activities/
│ ├── __init__.py
│ ├── extraction.py # extraire_texte()
│ ├── analyse.py # analyser_sentiment()
│ └── notifications.py # envoyer_alerte()
├── workflows/
│ ├── __init__.py
│ ├── analyse_document.py
│ └── surveillance.py
└── worker.py # Punto de entrada único
El archivo worker.py contiene entonces solo importaciones y la lógica de inicio, convirtiéndose en un inventario legible de lo que este proceso puede ejecutar:
import asyncio
import mistralai.workflows as workflows
from workflows.document_analysis import DocumentAnalysis
from workflows.monitoring import MentionMonitoring
async def main() -> None:
await workflows.run_worker([
DocumentAnalysis,
MentionMonitoring,
])
if __name__ == "__main__":
asyncio.run(main())
Iniciar el worker
uv run python worker.py
El worker muestra un mensaje de conexión y permanece activo, esperando tareas. Deberías ver algo similar a:
Worker connected. Listening for tasks...
Hasta que aparezca esta línea, no desencadenes nada. Primero, comprueba tu clave de API y la conexión de red.
El worker en producción
Un worker lanzado manualmente en una terminal desaparece tras la primera desconexión SSH. Entrégalo a un gestor de procesos: systemd, supervisor o pm2, que lo reiniciará automáticamente tras un fallo o un reinicio del sistema:
# Con pm2 (si Node.js está disponible)
pm2 start "uv run python worker.py" --name workflow-worker
# Con systemd (crea un archivo .service)
Este reinicio automático combina bien con la durabilidad: los flujos de trabajo en ejecución se reanudan por sí solos tan pronto como el nuevo proceso se conecta. En cuanto a los secretos, nunca codifiques la clave de API directamente en el archivo del worker, o acabará en tu repositorio de Git. El SDK lee la variable de entorno automáticamente:
import os
# El SDK lee automáticamente MISTRAL_API_KEY
# No es necesario pasarla explícitamente
Por último, considera el registro de eventos (logging). El worker emite mensajes a través del módulo estándar logging de Python. Una configuración sencilla al inicio te proporciona un rastro de las actividades ejecutadas, lo cual es valioso para entender qué estaba ocurriendo durante un incidente:
import logging
logging.basicConfig(level=logging.INFO)
Puntos clave
- El worker es el proceso que ejecuta tus flujos de trabajo y actividades localmente
workflows.run_worker([...])recibe una lista de clases de flujo de trabajo para ejecutar- Un único worker puede ejecutar múltiples flujos de trabajo diferentes
- El worker permanece activo y escucha tareas mientras el proceso esté en ejecución
- En producción, usa un gestor de procesos para mantener el worker en ejecución
- La clave de API se lee automáticamente desde
MISTRAL_API_KEY