Exécuter et tester un workflow
Op deze pagina
Leçon mise à jour le 3 novembre 2026 sur la base du SDK
mistralai3.7.0 : le suivi d’une exécution utilise désormaisclient.workflows.executions.get_workflow_execution_async, et le résultat est lu depuisresult. Addendum du jour même : les exemples précédents faisaient encore référence àexecution.id,execution.outputetexecution.error, qui sont absents du SDK, et comparaient le statut aux valeurs minuscules"completed"ou"failed"; ils utilisent désormaisexecution_id,result,wait_for_result=Trueet des statuts en majuscules. Source : client-python.
Déclencher un workflow
Vous avez écrit vos activités, défini votre workflow et démarré votre worker. Il vous reste maintenant à lancer une exécution. Deux options s’offrent à vous : le SDK Python ou un appel cURL vers l’API REST. La première convient à vos scripts et services Python ; la seconde est idéale pour des tests rapides en ligne de commande ou des déclencheurs provenant de systèmes non-Python (webhook, planificateur, backend dans un autre langage).
Trois conditions doivent être réunies avant tout déclenchement. Votre worker doit être en cours d’exécution (uv run python worker.py), votre clé API doit être définie dans MISTRAL_API_KEY, et le workflow doit être enregistré auprès de ce worker, c’est-à-dire figurer dans la liste passée à run_worker().
Déclenchement via le SDK Python
Rédigez le déclencheur dans un script distinct du worker, car le processus worker ne rend jamais la main :
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, # attend la fin et reçoit le résultat
)
print(f"Execution ID: {execution.execution_id}")
print(f"Result: {execution.result}")
if __name__ == "__main__":
asyncio.run(main())
Le workflow_identifier correspond exactement au name déclaré dans @workflows.workflow.define(), et les clés du dictionnaire input correspondent aux paramètres de votre méthode run. Exécutez ce script dans un terminal séparé, en laissant le premier occupé par le worker :
uv run python trigger.py
Avec wait_for_result=True, le SDK attend la fin de l’exécution et renvoie directement le résultat, ce qui rend les tests très lisibles pour les workflows courts. Sans ce paramètre, l’appel retourne immédiatement avec l’identifiant d’exécution, que vous devrez ensuite suivre (voir ci-dessous).
Déclenchement via cURL
Pour des tests rapides ou une intégration avec d’autres systèmes, l’API REST expose le même déclencheur :
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}'
Avec wait_for_result, la réponse contient le nom du workflow, l’identifiant d’exécution et son résultat ; ce sont les champs du modèle WorkflowExecutionSyncResponse du SDK :
{
"workflow_name": "salutation_workflow",
"execution_id": "…",
"result": {
"message": "Bonjour, Marie !"
}
}
Conservez cet execution_id : c’est la clé que vous utiliserez plus tard pour interroger l’exécution ou récupérer ses traces. Sans wait_for_result, la réponse décrit l’exécution en cours, y compris son status (initialement RUNNING).
Exemple de bout en bout
Reprenons l’exemple du pipeline d’analyse de documents, cette fois entièrement câblé. Le premier fichier combine les définitions et le démarrage du worker ; notez la troncature à 5000 caractères, qui protège à la fois la limite de taille des activités et votre budget de tokens.
Fichier workflow.py (worker + définitions)
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]} # Limite à 5000 caractères
@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())
Le second fichier déclenche le workflow et affiche le résultat, en gérant explicitement le cas d’échec — un réflexe à adopter dès votre premier script :
Fichier trigger.py (déclencheur)
import asyncio
from mistralai.client import Mistral
async def main():
client = Mistral()
print("Lancement du workflow...")
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}")
# Suivi de l'exécution jusqu'à complétion
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())
Exécution
Terminal 1 — Démarrage du worker :
uv run python workflow.py
Terminal 2 — Déclenchement de l’exécution :
uv run python trigger.py
Vérification des résultats
Le terminal du worker est votre premier point d’observation : il affiche les activités exécutées en temps réel, ainsi que leur durée, vous indiquant immédiatement quelle étape consomme le plus de temps.
[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
Pour les workflows longs, vous ne resterez évidemment pas collé au terminal. Une fois l’ID d’exécution obtenu, vous pouvez interroger son statut à tout moment depuis un autre processus :
execution = await client.workflows.executions.get_workflow_execution_async(
execution_id="exec_abc123"
)
print(f"Status: {execution.status}")
print(f"Result: {execution.result}")
La même opération est disponible via cURL, utile dans un script de surveillance :
curl https://api.mistral.ai/v1/workflows/executions/exec_abc123 \
-H "Authorization: Bearer $MISTRAL_API_KEY"
Gestion des erreurs
Un échec ne survient pas à la première exception : la plateforme tente d’abord de réexécuter l’activité selon sa politique de retry. Ce n’est qu’après épuisement des tentatives que l’exécution passe au statut FAILED (les statuts du SDK sont en majuscules : RUNNING, COMPLETED, FAILED, CANCELED, TERMINATED, TIMED_OUT, etc.), et votre code appelant doit gérer ce cas au lieu de supposer qu’un result est toujours présent :
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 réponse ne contient pas de message d’erreur : la cause apparaît dans l’historique d’exécution et les logs (get_workflow_execution_history_async, get_workflow_execution_logs_async). Pour identifier l’activité défaillante et la séquence qui y a conduit, vous analyserez les traces OpenTelemetry, abordées dans la leçon 14.
Tests locaux
La navette entre deux terminaux devient rapidement fastidieuse lors du développement. Pour le développement, un seul script peut démarrer le worker en arrière-plan, déclencher le workflow, puis tout arrêter :
import asyncio
import mistralai.workflows as workflows
# ... définitions des activités et du workflow ...
async def main():
# Démarrage du worker en arrière-plan
worker_task = asyncio.create_task(
workflows.run_worker([MonWorkflow])
)
# Attente que le worker soit prêt
await asyncio.sleep(2)
# Déclenchement du workflow
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}")
# Arrêt du worker
worker_task.cancel()
if __name__ == "__main__":
asyncio.run(main())
Le asyncio.sleep(2) laisse au worker le temps d’établir sa connexion avant le déclenchement, et le worker_task.cancel() final empêche le script de rester bloqué indéfiniment. Réservez cette configuration au développement : en production, le worker et les déclencheurs restent des processus séparés avec des cycles de vie indépendants.
Belangrijkste punten
- Deux méthodes de déclenchement : SDK Python (
execute_workflow_async) et API REST (cURL) - Le worker doit être en cours d’exécution pour que le workflow s’exécute
- Avec
wait_for_result=True, le SDK attend la fin et renvoie le résultat (result) ; sinon, il renvoie l’execution_idà suivre - Utilisez
client.workflows.executions.get_workflow_execution_async()pour vérifier le statut d’une exécution - Les statuts sont en majuscules (
RUNNING,COMPLETED,FAILED, etc.) ; les causes d’échec apparaissent dans l’historique d’exécution, les logs et les traces - Pour le développement, combinez worker et déclencheur dans un seul script utilisant
asyncio