Créer un workflow
In questa pagina
Le rôle du workflow
Le workflow constitue la couche d’orchestration de ton application. Il définit ce qui doit se produire, dans quel ordre et sous quelles conditions, sans exécuter le travail lui-même. Concrètement, il coordonne les activités, attend des événements externes, gère les minuteurs et les branchements conditionnels, mais il ne touche jamais au réseau ni au disque.
Tu peux résumer cela en une phrase à garder en tête chaque fois que tu relis du code : les activités font le travail, le workflow dirige. Si tu vois httpx ou open() à l’intérieur d’une classe de workflow, quelque chose doit être déplacé.
Structure d’un workflow
Un workflow est une classe Python décorée avec @workflows.workflow.define(), contenant une méthode d’entrée décorée avec @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:
"""Point d'entrée du workflow."""
resultat = await saluer(nom)
return resultat
Le décorateur @workflows.workflow.define(name="...") enregistre la classe en tant que workflow. Le name qu’il reçoit est l’identifiant unique que tu utiliseras pour déclencher une exécution : c’est cette chaîne, et non le nom de la classe Python, que l’appelant voit. Le décorateur @workflows.workflow.entrypoint marque la méthode appelée au démarrage. Le premier paramètre, self, reste l’instance de la classe, comme dans tout objet Python, et chaque appel d’activité utilise await.
Exemple complet : pipeline de traitement
Voici un workflow réaliste qui orchestre plusieurs activités pour traiter un document. Remarque la répartition des tâches : les trois fonctions en haut contiennent tout le code qui touche au monde extérieur, tandis que la classe en bas se contente d’enchaîner les appels await et d’assembler un résultat.
import mistralai.workflows as workflows
from mistralai.client import Mistral
# --- Activités ---
@workflows.activity()
async def extraire_texte(url_document: str) -> dict:
"""Télécharger et extraire le texte d'un document."""
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:
"""Analyser le texte avec Mistral pour en extraire les points clés."""
client = Mistral()
response = await client.chat.complete_async(
model="mistral-large-latest",
messages=[
{"role": "system", "content": "Extract the 5 key points from this text."},
{"role": "user", "content": texte}
]
)
return {"analyse": response.choices[0].message.content}
@workflows.activity()
async def sauvegarder_resultat(analyse: dict) -> dict:
"""Sauvegarder le résultat de l'analyse."""
async with httpx.AsyncClient() as client:
response = await client.post(
"https://api.example.com/rapports",
json=analyse
)
return {"id_rapport": response.json()["id"]}
# --- Workflow ---
@workflows.workflow.define(name="pipeline_analyse_document")
class PipelineAnalyseDocument:
@workflows.workflow.entrypoint
async def run(self, url_document: str) -> dict:
"""Orchestrer l'extraction, l'analyse et la sauvegarde."""
# Étape 1 : Extraire le texte
extraction = await extraire_texte(url_document)
# Étape 2 : Analyser avec Mistral
analyse = await analyser_avec_mistral(extraction["texte"])
# Étape 3 : Sauvegarder
sauvegarde = await sauvegarder_resultat(analyse)
return {
"url_source": url_document,
"longueur_texte": extraction["longueur"],
"id_rapport": sauvegarde["id_rapport"]
}
Chaque await dans le workflow constitue un point de persistance. Il vaut la peine de le vérifier mentalement avec l’exemple ci-dessus : si le processus échoue entre l’étape 2 et l’étape 3, le document ne sera pas retéléchargé et le modèle ne sera pas rappelé, donc aucun coût de token supplémentaire. Le workflow reprendra directement à l’étape de sauvegarde.
Durabilité du workflow
Les workflows survivent aux redémarrages, aux pannes d’infrastructure et aux erreurs transitoires car la plateforme enregistre chaque événement et reconstruit l’état du workflow lors de la relecture. Cette reconstruction n’est fiable que sous une condition, mentionnée plus tôt : le code du workflow doit toujours produire la même séquence d’opérations pour les mêmes entrées. C’est la contrainte de déterminisme. Nous aborderons les détails dans la leçon 8.
Workflow avec branchement conditionnel
Un workflow ne se limite pas à une séquence linéaire. Il peut contenir une logique conditionnelle, comme dans cet exemple de traitement de commande où le chemin dépend du statut du stock :
@workflows.workflow.define(name="traitement_commande")
class OrderProcessing:
@workflows.workflow.entrypoint
async def run(self, order: dict) -> dict:
# Vérifier le stock
stock = await check_stock(order["produit_id"])
if stock["disponible"]:
# Chemin standard
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:
# Chemin alternatif
await notify_stockout(order["email"], order["produit_id"])
return {"status": "rupture_stock"}
Les branchements if/else sont entièrement pris en charge. La seule contrainte concerne la matière utilisée pour la décision : le résultat du branchement doit dépendre de la valeur de retour d’une activité (une valeur enregistrée dans le journal et rejouée à l’identique), et non d’un appel direct à un service externe depuis le workflow. Ici, verifier_stock interroge l’inventaire au sein d’une activité, et l’instruction if lit uniquement un dictionnaire qui a déjà été persisté.
Entrées avec Pydantic
Un workflow qui prend six paramètres positionnels devient rapidement illisible. Pour des entrées structurées, utilise des modèles Pydantic, qui fournissent également une validation de type au début de l’exécution :
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 point de vigilance lors du déclenchement de ce workflow : lorsque tu utilises un BaseModel, les champs deviennent des clés de premier niveau dans l’entrée JSON envoyée au workflow. Tu enverras {"type_rapport": ..., "date_debut": ...}, et non un objet imbriqué sous une clé params.
Bonnes pratiques
Quatre habitudes font la différence sur le long terme. Premièrement, respecte une responsabilité unique par workflow : mélanger la facturation et le suivi des ventes dans la même classe rend impossible la relecture de l’un sans l’autre. Ensuite, sois attentif au nommage, car le name du workflow est un identifiant public appelé depuis d’autres systèmes : "traitement_commande" est maintenable, "workflow_1" ne l’est pas. N’introduis aucune E/S dans le workflow : chaque appel réseau, accès fichier ou requête base de données appartient à une activité. Enfin, garde le code du workflow simple en déléguant la logique complexe (parsing, transformations, calculs lourds) aux activités, où elle peut être testée de manière isolée sans contraintes de déterminisme.
Punti chiave
- Un workflow est une classe décorée avec
@workflows.workflow.define()qui orchestre des activités - La méthode
@workflows.workflow.entrypointest le point d’entrée appelé au démarrage - Chaque
awaitd’activité est un point de persistance (reprise automatique en cas d’échec) - Les branchements conditionnels et les boucles sont pris en charge
- Utilise des modèles Pydantic pour les paramètres d’entrée structurés
- Le workflow ne doit contenir aucune opération d’E/S directe