Crear un flujo de trabajo
En esta página
La función del flujo de trabajo
El flujo de trabajo es la capa de orquestación de tu aplicación. Define qué debe ocurrir, en qué orden y bajo qué condiciones, sin ejecutar el trabajo en sí. En concreto, coordina actividades, espera eventos externos, gestiona temporizadores y ramas condicionales, pero nunca toca la red ni el disco.
Puedes resumir esto en una frase que debes tener presente cada vez que revises código: las actividades hacen el trabajo, el flujo de trabajo dirige. Si ves httpx o open() dentro de una clase de flujo de trabajo, algo necesita ser movido.
Estructura del flujo de trabajo
Un flujo de trabajo es una clase de Python decorada con @workflows.workflow.define(), que contiene un método de entrada decorado con @workflows.workflow.entrypoint:
import mistralai.workflows as workflows
@workflows.workflow.define(name="mon_premier_workflow")
class MonPremierWorkflow:
@workflows.workflow.entrypoint
async def run(self, nom: str) -> dict:
"""Punto de entrada del flujo de trabajo."""
resultat = await saluer(nom)
return resultat
El decorador @workflows.workflow.define(name="...") registra la clase como un flujo de trabajo. El name que recibe es el identificador único que usarás para desencadenar una ejecución; esta cadena, no el nombre de la clase de Python, es lo que ve el llamador. El decorador @workflows.workflow.entrypoint marca el método que se llama al inicio. El primer parámetro, self, sigue siendo la instancia de la clase, como en cualquier objeto de Python, y cada llamada a una actividad usa await.
Ejemplo completo: canalización de procesamiento
Aquí tienes un flujo de trabajo realista que orquesta múltiples actividades para procesar un documento. Observa la división del trabajo: las tres funciones superiores contienen todo el código que toca el mundo exterior, mientras que la clase inferior simplemente encadena llamadas await y ensambla un resultado.
import mistralai.workflows as workflows
from mistralai.client import Mistral
# --- Actividades ---
@workflows.activity()
async def extraire_texte(url_document: str) -> dict:
"""Descargar y extraer texto de un documento."""
async with httpx.AsyncClient() as client:
response = await client.get(url_document)
texte = response.text
return {"texte": texte, "longueur": len(texte)}
@workflows.activity()
async def analyser_avec_mistral(texte: str) -> dict:
"""Analizar texto con Mistral para extraer puntos clave."""
client = Mistral()
response = await client.chat.complete_async(
model="mistral-large-latest",
messages=[
{"role": "system", "content": "Extrae los 5 puntos clave de este texto."},
{"role": "user", "content": texte}
]
)
return {"analyse": response.choices[0].message.content}
@workflows.activity()
async def sauvegarder_resultat(analyse: dict) -> dict:
"""Guardar el resultado del análisis."""
async with httpx.AsyncClient() as client:
response = await client.post(
"https://api.example.com/rapports",
json=analyse
)
return {"id_rapport": response.json()["id"]}
# --- Flujo de trabajo ---
@workflows.workflow.define(name="pipeline_analyse_document")
class PipelineAnalyseDocument:
@workflows.workflow.entrypoint
async def run(self, url_document: str) -> dict:
"""Orquestar extracción, análisis y guardado."""
# Paso 1: Extraer texto
extraction = await extraire_texte(url_document)
# Paso 2: Analizar con Mistral
analyse = await analyser_avec_mistral(extraction["texte"])
# Paso 3: Guardar
sauvegarde = await sauvegarder_resultat(analyse)
return {
"url_source": url_document,
"longueur_texte": extraction["longueur"],
"id_rapport": sauvegarde["id_rapport"]
}
Cada await en el flujo de trabajo constituye un punto de persistencia. Merece la pena verificarlo mentalmente con el ejemplo anterior: si el proceso falla entre el paso 2 y el paso 3, el documento no se volverá a descargar ni se llamará de nuevo al modelo, por lo que no habrá cargos adicionales de tokens. El flujo de trabajo se reanudará directamente en el paso de guardado.
Durabilidad del flujo de trabajo
Los flujos de trabajo sobreviven a reinicios, fallos de infraestructura y errores transitorios porque la plataforma registra cada evento y reconstruye el estado del flujo de trabajo durante la repetición. Esta reconstrucción es fiable solo bajo una condición, mencionada anteriormente: el código del flujo de trabajo debe producir siempre la misma secuencia de operaciones para las mismas entradas. Esta es la restricción de determinismo. Cubriremos los detalles en la lección 8.
Flujo de trabajo con ramificación condicional
Un flujo de trabajo no se limita a una secuencia lineal. Puede contener lógica condicional, como en este ejemplo de procesamiento de pedidos donde la ruta depende del estado del stock:
@workflows.workflow.define(name="traitement_commande")
class OrderProcessing:
@workflows.workflow.entrypoint
async def run(self, order: dict) -> dict:
# Comprobar stock
stock = await check_stock(order["produit_id"])
if stock["disponible"]:
# Ruta estándar
payment = await process_payment(order["montant"])
shipment = await prepare_shipment(order)
await send_confirmation(order["email"], shipment)
return {"status": "confirmée", "tracking": shipment["tracking"]}
else:
# Ruta alternativa
await notify_stockout(order["email"], order["produit_id"])
return {"status": "rupture_stock"}
Las ramas if/else son totalmente compatibles. La única restricción concierne al material utilizado para la decisión: el resultado de la rama debe depender del valor de retorno de una actividad, un valor registrado en el log y repetido idénticamente, no de una llamada directa a un servicio externo desde el flujo de trabajo. Aquí, verifier_stock consulta el inventario dentro de una actividad, y la sentencia if lee solo un diccionario que ya ha sido persistido.
Entradas con Pydantic
Un flujo de trabajo que toma seis parámetros posicionales se vuelve rápidamente ilegible. Para entradas estructuradas, usa modelos de Pydantic, que también proporcionan validación de tipos al inicio de la ejecución:
from pydantic import BaseModel
class ReportParams(BaseModel):
report_type: str
include_details: bool = False
start_date: str
end_date: str
@workflows.workflow.define(name="generation_rapport")
class ReportGeneration:
@workflows.workflow.entrypoint
async def run(self, params: ReportParams) -> dict:
data = await collect_data(params.report_type, params.start_date, params.end_date)
if params.include_details:
data = await enrich_data(data)
report = await generate_pdf_report(data)
return {"url_rapport": report["url"]}
Un punto de precaución al desencadenar este flujo de trabajo: cuando usas un BaseModel, los campos se convierten en claves de nivel superior en la entrada JSON enviada al flujo de trabajo. Enviarás {"type_rapport": ..., "date_debut": ...}, no un objeto anidado bajo una clave params.
Buenas prácticas
Cuatro hábitos marcan la diferencia a largo plazo. Primero, cíñete a una responsabilidad por flujo de trabajo: mezclar facturación y seguimientos de ventas en la misma clase hace imposible repetir uno sin el otro. A continuación, presta atención a la nomenclatura, ya que el name del flujo de trabajo es un identificador público llamado desde otros sistemas; "traitement_commande" es mantenible, "workflow_1" no lo es. No introduzcas ninguna E/S en el flujo de trabajo: cada llamada a la red, acceso a archivos o consulta a la base de datos pertenece a una actividad. Finalmente, mantén el código del flujo de trabajo simple delegando la lógica compleja (análisis, transformaciones, cálculos pesados) a las actividades, donde puede probarse de forma aislada sin restricciones de determinismo.
Puntos clave
- Un flujo de trabajo es una clase decorada con
@workflows.workflow.define()que orquesta actividades - El método
@workflows.workflow.entrypointes el punto de entrada llamado al inicio - Cada
awaitde actividad es un punto de persistencia (reanudación automática en caso de fallo) - Las ramas condicionales y los bucles son compatibles
- Usa modelos de Pydantic para parámetros de entrada estructurados
- El flujo de trabajo no debe contener ninguna operación de E/S directa