Ejecutar y probar un flujo de trabajo
En esta página
Lección actualizada el 3 de noviembre de 2026 según el SDK
mistralai3.7.0: el seguimiento de una ejecución utiliza ahoraclient.workflows.executions.get_workflow_execution_async, y el resultado se lee desderesult. Addendum del mismo día: los ejemplos anteriores seguían haciendo referencia aexecution.id,execution.outputyexecution.error, que no existen en el SDK, y comparaban el estado con las cadenas en minúsculas"completed"o"failed"; ahora usanexecution_id,result,wait_for_result=Truey estados en mayúsculas. Fuente: client-python.
Disparar un flujo de trabajo
Ya has escrito tus actividades, definido tu flujo de trabajo e iniciado tu worker. Ahora necesitas lanzar una ejecución. Tienes dos opciones: el SDK de Python o una llamada cURL a la API REST. La primera encaja en tus scripts y servicios de Python; la segunda sirve para pruebas rápidas desde la línea de comandos o para disparadores desde sistemas que no sean Python: un webhook, un planificador o un backend escrito en otro lenguaje.
Deben cumplirse tres condiciones antes de disparar nada. Tu worker debe estar en ejecución (uv run python worker.py), tu clave de API debe estar establecida en MISTRAL_API_KEY, y el flujo de trabajo debe estar registrado con ese worker, lo que significa que aparece en la lista pasada a run_worker().
Disparo mediante el SDK de Python
Escribe el disparador en un script separado del worker, ya que el proceso del worker nunca devuelve el control:
import asyncio
from mistralai.client import Mistral
async def main():
client = Mistral()
execution = await client.workflows.execute_workflow_async(
workflow_identifier="salutation_workflow",
input={"nom": "Marie"},
wait_for_result=True, # espera a la finalización y recibe el resultado
)
print(f"Execution ID: {execution.execution_id}")
print(f"Result: {execution.result}")
if __name__ == "__main__":
asyncio.run(main())
El workflow_identifier coincide exactamente con el name declarado en @workflows.workflow.define(), y las claves del diccionario input corresponden a los parámetros de tu método run. Ejecuta este script en un terminal separado, dejando el primero ocupado por el worker:
uv run python trigger.py
Con wait_for_result=True, el SDK espera a que la ejecución termine y devuelve el resultado directamente, lo que hace que las pruebas sean muy legibles para flujos de trabajo cortos. Sin este parámetro, la llamada devuelve inmediatamente el identificador de la ejecución, que luego deberás seguir (ver más abajo).
Disparo mediante cURL
Para pruebas rápidas o integración con otros sistemas, la API REST expone el mismo disparador:
curl -X POST https://api.mistral.ai/v1/workflows/salutation_workflow/execute \
-H "Authorization: Bearer $MISTRAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input": {"nom": "Marie"}, "wait_for_result": true}'
Con wait_for_result, la respuesta contiene el nombre del flujo de trabajo, el identificador de la ejecución y su resultado; estos son los campos del modelo WorkflowExecutionSyncResponse del SDK:
{
"workflow_name": "salutation_workflow",
"execution_id": "…",
"result": {
"message": "Bonjour, Marie !"
}
}
Guarda este execution_id: es la clave que usarás más adelante para consultar la ejecución o recuperar sus trazas. Sin wait_for_result, la respuesta describe la ejecución en curso, incluyendo su status (RUNNING inicialmente).
Ejemplo de extremo a extremo
Retomemos el ejemplo de la tubería de análisis de documentos, esta vez totalmente conectado. El primer archivo combina las definiciones y el arranque del worker; obsérvese el truncamiento a 5000 caracteres, que protege tanto el límite de tamaño de la actividad como tu presupuesto de tokens.
Archivo workflow.py (worker + definiciones)
import asyncio
import httpx
import mistralai.workflows as workflows
from mistralai.client import Mistral
@workflows.activity()
async def extraire_texte(url: str) -> dict:
async with httpx.AsyncClient() as client:
response = await client.get(url)
return {"texte": response.text[:5000]} # Limitar a 5000 caracteres
@workflows.activity()
async def resumer_texte(texte: str) -> dict:
client = Mistral()
response = await client.chat.complete_async(
model="mistral-large-latest",
messages=[
{"role": "system", "content": "Summarize in 3 sentences."},
{"role": "user", "content": texte}
]
)
return {"resume": response.choices[0].message.content}
@workflows.workflow.define(name="resume_page_web")
class ResumePageWeb:
@workflows.workflow.entrypoint
async def run(self, url: str) -> dict:
extraction = await extraire_texte(url)
resume = await resumer_texte(extraction["texte"])
return {
"url_source": url,
"resume": resume["resume"]
}
async def main() -> None:
await workflows.run_worker([ResumePageWeb])
if __name__ == "__main__":
asyncio.run(main())
El segundo archivo dispara el flujo de trabajo y muestra el resultado, gestionando explícitamente el caso de fallo: un reflejo que debes adoptar desde tu primer script:
Archivo trigger.py (disparador)
import asyncio
from mistralai.client import Mistral
async def main():
client = Mistral()
print("Lanzando flujo de trabajo...")
execution = await client.workflows.execute_workflow_async(
workflow_identifier="resume_page_web",
input={"url": "https://example.com/article"},
)
print(f"Execution launched: {execution.execution_id}")
# Seguir la ejecución hasta su finalización
while True:
suivi = await client.workflows.executions.get_workflow_execution_async(
execution_id=execution.execution_id
)
if suivi.status not in ("RUNNING", "RETRYING_AFTER_ERROR"):
break
await asyncio.sleep(2)
if suivi.status == "COMPLETED":
print(f"Summary: {suivi.result['resume']}")
else:
print(f"Execution finished with status {suivi.status}")
if __name__ == "__main__":
asyncio.run(main())
Ejecución
Terminal 1 — Iniciar el worker:
uv run python workflow.py
Terminal 2 — Disparar la ejecución:
uv run python trigger.py
Comprobar resultados
El terminal del worker es tu primer punto de observación: muestra las actividades ejecutadas en tiempo real, junto con su duración, indicándote de inmediato qué paso consume más tiempo.
[INFO] Executing activity: extraire_texte
[INFO] Activity completed: extraire_texte (1.2s)
[INFO] Executing activity: resumer_texte
[INFO] Activity completed: resumer_texte (3.4s)
[INFO] Workflow completed: resume_page_web
Para flujos de trabajo largos, obviamente no te quedarás pegado al terminal. Una vez que tengas el ID de ejecución, puedes consultar su estado en cualquier momento desde otro proceso:
execution = await client.workflows.executions.get_workflow_execution_async(
execution_id="exec_abc123"
)
print(f"Status: {execution.status}")
print(f"Result: {execution.result}")
La misma operación está disponible vía cURL, útil en un script de monitorización:
curl https://api.mistral.ai/v1/workflows/executions/exec_abc123 \
-H "Authorization: Bearer $MISTRAL_API_KEY"
Gestión de errores
Un fallo no ocurre ante la primera excepción: la plataforma reintenta primero la actividad según su política de reintentos. Solo cuando se agotan los reintentos, la ejecución pasa al estado FAILED (los estados del SDK están en mayúsculas: RUNNING, COMPLETED, FAILED, CANCELED, TERMINATED, TIMED_OUT, etc.), y tu código de llamada debe gestionar este caso en lugar de asumir que un result está siempre presente:
execution = await client.workflows.executions.get_workflow_execution_async(
execution_id="exec_abc123"
)
if execution.status == "FAILED":
print(f"Execution {execution.execution_id} failed")
La respuesta no contiene un mensaje de error: la causa aparece en el historial de ejecución y en los registros (get_workflow_execution_history_async, get_workflow_execution_logs_async). Para identificar la actividad defectuosa y la secuencia que condujo a ella, analizarás las trazas de OpenTelemetry, que se tratan en la Lección 14.
Pruebas locales
Ir y venir entre dos terminales se vuelve rápidamente tedioso durante el desarrollo. Para el desarrollo, un único script puede iniciar el worker en segundo plano, disparar el flujo de trabajo y luego detenerlo todo:
import asyncio
import mistralai.workflows as workflows
# ... definiciones de actividades y flujos de trabajo ...
async def main():
# Iniciar worker en segundo plano
worker_task = asyncio.create_task(
workflows.run_worker([MonWorkflow])
)
# Esperar a que el worker esté listo
await asyncio.sleep(2)
# Disparar flujo de trabajo
from mistralai.client import Mistral
client = Mistral()
execution = await client.workflows.execute_workflow_async(
workflow_identifier="mon_workflow",
input={"test": True},
wait_for_result=True,
)
print(f"Result: {execution.result}")
# Detener worker
worker_task.cancel()
if __name__ == "__main__":
asyncio.run(main())
El asyncio.sleep(2) da tiempo al worker para establecer su conexión antes del disparo, y el worker_task.cancel() final evita que el script se quede colgado indefinidamente. Reserva esta configuración para el desarrollo: en producción, el worker y los disparadores permanecen como procesos separados con ciclos de vida independientes.
Puntos clave
- Dos métodos de disparo: SDK de Python (
execute_workflow_async) y API REST (cURL) - El worker debe estar en ejecución para que el flujo de trabajo se ejecute
- Con
wait_for_result=True, el SDK espera a la finalización y devuelve el resultado (result); de lo contrario, devuelve elexecution_idpara hacer seguimiento - Usa
client.workflows.executions.get_workflow_execution_async()para comprobar el estado de una ejecución - Los estados están en mayúsculas (
RUNNING,COMPLETED,FAILED, etc.); las causas de fallo aparecen en el historial de ejecución, los registros y las trazas - Para el desarrollo, combina worker y disparador en un único script usando
asyncio