La plupart des bibliothèques de construction d'agents décrivent un flux comme un graphe : des nœuds, des arêtes et des conditions de transition. Workflows choisit un autre concept. Ici, il y a des étapes qui écoutent des événements d'un type donné et qui émettent elles-mêmes des événements, et l'exécution consiste pour le moteur à livrer chaque événement à l'étape qui s'y est abonnée.
La différence paraît cosmétique et ne l'est pas. Dans un graphe, tu dois dessiner chaque arête à l'avance. Dans un montage piloté par événements, ajouter une étape revient à écrire une fonction qui écoute un événement existant, sans rien toucher d'autre.
Le nom mérite d'être clarifié tout de suite, car il induit en erreur. Workflows est né de la bibliothèque LlamaIndex, connue pour la récupération de documents, mais c'est aujourd'hui un paquet séparé avec son propre dépôt et sa propre trajectoire de développement. Il peut être utilisé sans le reste de cet écosystème.
Ton premier workflow
pip install llama-index-workflowsUne étape est une méthode avec un décorateur, qui prend un événement d'un type et renvoie un événement d'un autre. Toute la logique de contrôle se trouve dans ces types.
from workflows import Workflow, step, Context
from workflows.events import StartEvent, StopEvent, Event
class QuestionExpanded(Event):
question: str
class ChunksFound(Event):
chunks: list[str]
class Assistant(Workflow):
@step
async def expand(self, ev: StartEvent) -> QuestionExpanded:
full = await rephrase(ev.question)
return QuestionExpanded(question=full)
@step
async def search(self, ev: QuestionExpanded) -> ChunksFound:
return ChunksFound(chunks=await store.search(ev.question))
@step
async def answer(self, ev: ChunksFound) -> StopEvent:
return StopEvent(result=await model.ask(ev.chunks))
result = await Assistant(timeout=60).run(question="What is the notice period?")Nulle part tu n'as écrit que la recherche suit l'expansion de la question. Cela découle des types : l'étape d'expansion renvoie un événement auquel l'étape de recherche s'est abonnée. L'ordre est une conséquence des déclarations plutôt qu'une description séparée qui pourrait se désynchroniser d'elles.
Cela apporte un avantage pratique que l'on apprécie vers la troisième semaine de travail. Tu ne peux pas construire un flux avec une arête qui ne mène nulle part, car un événement sans récepteur se voit immédiatement.
Contexte et état
Les étapes ne voient pas les variables les unes des autres, donc faire passer de l'état en dehors des charges des événements passe par un contexte rattaché à l'exécution.
@step
async def gather(self, ctx: Context, ev: ChunksFound) -> StopEvent:
count = await ctx.store.get("attempts", default=0)
await ctx.store.set("attempts", count + 1)
return StopEvent(result=...)La séparation entre événements et contexte mérite d'être réfléchie au départ, car on la modifie à contrecœur plus tard. La règle qui fonctionne en pratique se lit ainsi : un événement porte ce dont l'étape suivante a besoin, et le contexte porte ce qui concerne toute l'exécution.
Un numéro de dossier, un identifiant d'utilisateur et un compteur de tentatives appartiennent au contexte. Un résultat de recherche transmis plus loin appartient à un événement. Tout déverser dans le contexte produit un flux où l'on ne voit pas ce qui dépend de quoi, c'est-à-dire exactement ce que ce modèle devait éviter.
Le contexte peut être écrit sous forme de dictionnaire et restauré ensuite. Cela ouvre deux possibilités : reprendre une exécution interrompue, et conserver l'état entre des requêtes HTTP sans garder un processus en mémoire.
La sérialisation gère les objets décrits par un modèle de données, en stockant le nom complet de la classe à côté des valeurs, donc la restauration renvoie le bon type plutôt qu'un dictionnaire brut. Garde cependant dans le contexte des données plutôt que des objets qui portent des connexions ou des handles de ressources, car ceux-ci ne pointeront sur rien de significatif une fois restaurés.
Points de contrôle et reprise
Il n'y a pas de checkpointer intégré ici, ce qu'il vaut mieux savoir d'avance. La bibliothèque fournit la matière première : après chaque étape terminée, le moteur émet sur le flux un événement interne qui porte un instantané de l'état, le nom de l'événement d'entrée et le nom de l'événement de sortie, et c'est à toi de persister cet instantané.
En pratique, cela fait une douzaine de lignes de code. Tu écoutes le flux de l'exécution avec les événements internes exposés, tu déverses le contexte dans un dictionnaire à chaque fin d'étape, et tu le mets où tu veux. La reprise consiste à reconstruire le contexte à partir de ce dictionnaire et à le passer à l'exécution suivante du flux, dans un autre processus aussi.
L'intérêt se voit dans les factures du modèle. Un flux de huit étapes dont la septième échoue sur une erreur d'API externe coûte six appels au modèle par tentative de réparation en l'absence de points de contrôle. Avec des points de contrôle, il n'en coûte aucun, car tu reprends depuis le point d'échec.
Il y a toutefois une réserve à connaître avant la production. La reprise est « au moins une fois ». Les étapes terminées ne s'exécutent pas à nouveau, car leur sortie se trouve déjà dans l'état restauré, tandis qu'une étape interrompue en cours de route s'exécute depuis le début, donc ses effets de bord doivent pouvoir être répétés sans danger.
Le second avantage concerne les flux qui impliquent une personne. Une étape peut émettre un événement qui attend une décision, avec l'état sauvegardé aussi longtemps que nécessaire. Un agent prépare une proposition de réponse pour un client, une personne l'approuve dans un panneau, le flux continue, et six heures ainsi qu'un redémarrage de serveur s'écoulent entre-temps.
Prévois où va cet état avant d'écrire ton premier flux de production. La mémoire du processus suffit pour un prototype et échoue au premier déploiement, car les exécutions lancées avant sont perdues.
Concurrence et branchements
C'est ici que le modèle événementiel montre son avantage sur un graphe, car la concurrence en découle naturellement.
Une étape peut émettre plusieurs événements à la fois, et les étapes à l'écoute démarrent alors simultanément. Collecter les résultats revient à attendre un nombre donné d'événements d'un type.
@step
async def fan_out(self, ctx: Context, ev: QuestionExpanded) -> None:
for source in ["documents", "database", "web"]:
ctx.send_event(SearchIn(source=source, question=ev.question))
@step
async def gather(self, ctx: Context, ev: PartialResult) -> StopEvent | None:
results = ctx.collect_events(ev, [PartialResult] * 3)
if results is None:
return None
return StopEvent(result=merge(results))Renvoyer une valeur vide signifie que l'étape n'a pas encore l'ensemble complet et attend d'autres événements. Le moteur l'appelle à chaque résultat entrant jusqu'à ce que l'ensemble soit complet.
Ce motif couvre la plupart des besoins réels : chercher dans plusieurs sources à la fois, faire juger une réponse par plusieurs relecteurs, faire des appels d'API indépendants. Le temps gagné égale la différence entre la somme des durées et l'étape la plus lente, ce qui sur trois appels au modèle représente généralement les deux tiers.
Il y a un piège à connaître. Si l'un des événements n'arrive jamais, parce que l'étape qui l'émet a échoué, la collecte attend jusqu'à l'expiration du timeout. Le timeout défini sur le flux est ici une sauvegarde plutôt qu'une formalité.
Boucles, conditions et retours
Le modèle événementiel gère le branchement différemment d'un graphe, et les trois constructions les plus courantes méritent d'être vues.
Une condition est une étape qui renvoie l'un de plusieurs événements possibles. Tu déclares le type de retour comme une union de types, et le moteur livre l'événement émis au bon récepteur.
@step
async def judge(self, ev: AnswerReady) -> StopEvent | ReviseAgain:
if await score(ev.text) >= 0.8:
return StopEvent(result=ev.text)
return ReviseAgain(text=ev.text, notes=await collect_notes(ev.text))Une boucle naît du même mécanisme : l'étape de révision émet un événement qui retourne à l'étape de jugement. Il n'y a pas de concept séparé de cycle, car un cycle est simplement un événement qui remonte le flux.
Cette simplicité a un prix qu'il faut payer en connaissance de cause. Une boucle sans compteur tourne jusqu'à l'expiration du timeout, et chaque tour coûte des appels au modèle. Un compteur de tentatives conservé dans le contexte et vérifié dans la condition fait trois lignes de code dont l'omission peut coûter des dizaines de dollars sur un seul déploiement raté.
La troisième construction est l'arrêt anticipé. Une étape qui renvoie un événement d'arrêt termine toute l'exécution quoi qu'il se passe dans les branches parallèles. Cela aide pour la validation des entrées et pour détecter qu'un travail supplémentaire est inutile.
Tester les workflows
Une structure par étapes a un avantage facile à manquer : chaque étape est une fonction ordinaire qui prend un objet et renvoie un objet, donc elle se teste sans rien exécuter d'autre.
Cela signifie que la logique de branchement peut être vérifiée sans appeler de modèle. L'étape qui décide si une réponse est assez bonne se teste en lui passant un événement préparé et en vérifiant quel type elle a renvoyé. Une seconde au lieu de trente et zéro coût au lieu d'un appel au modèle.
Le deuxième niveau consiste à tester un flux entier en remplaçant les appels externes. En mettant des stubs à la place du modèle et de la recherche, tu vérifies si les étapes s'enchaînent dans l'ordre attendu et si les conditions mènent où elles le doivent.
Le troisième niveau, le plus précieux et le plus souvent omis, est un ensemble de cas réels avec des résultats attendus, exécutés sur un vrai modèle. Seul cela répond à la question de savoir si un changement du prompt système a amélioré quelque chose. Sans cela, le jugement se réduit à une impression tirée de quelques essais manuels, et les impressions trompent régulièrement.
Des agents par-dessus
La bibliothèque fournit aussi des classes d'agents prêtes à l'emploi, construites sur le même mécanisme, donc tu n'as pas besoin d'écrire la boucle d'outils de zéro.
from llama_index.core.agent.workflow import FunctionAgent
agent = FunctionAgent(
tools=[check_stock, place_order],
llm=model,
system_prompt="You handle orders. Always check stock before placing one.",
)
response = await agent.run("Order two pairs of shoes in size 42.")Comme un agent est un workflow, il peut être intégré comme étape dans un plus grand. C'est la bonne façon de combiner les deux niveaux : décris un processus aux étapes connues comme un flux, et confie à un agent l'étape unique qui demande du jugement.
L'inverse, confier un processus entier à un seul agent avec quinze outils, produit quelque chose qui fonctionne en démo et résiste au diagnostic quand il échoue.
Workflows face aux alternatives
| Option | Point fort | Faiblesse | À choisir quand |
|---|---|---|---|
| LlamaIndex Workflows | Des événements au lieu d'un graphe, concurrence facile | Communauté plus petite que le leader | Un projet qui utilise la couche de données LlamaIndex |
| LangGraph | Maturité, outils d'observabilité, grande communauté | Plus de concepts autour de l'état | État complexe et diagnostic poussé |
| Microsoft Agent Framework | Une variante .NET, support à long terme | Attirance vers Azure | Une entreprise sur les technologies Microsoft |
| Pydantic AI | Typage, abstraction minimale | Périmètre d'orchestration plus étroit | Un agent avec une structure de résultat fixe |
| Google ADK | Le même modèle conceptuel en cinq langages | Attirance vers l'infrastructure Google | Une équipe qui travaille hors de Python |
Le premier critère est banal : si ta couche de récupération de documents tourne déjà sur LlamaIndex, ce choix t'évite de traduire entre les concepts de deux bibliothèques.
Le deuxième concerne la façon dont tu penses le flux. Un graphe convient à un processus avec une machine à états explicite, avec boucles et retours. Les événements conviennent à un processus qui est un ensemble de réactions à ce qui s'est passé, et où beaucoup de choses s'exécutent en parallèle.
Le troisième, comme toujours, est de savoir si c'est nécessaire. Trois appels au modèle en séquence n'ont besoin d'aucune de ces bibliothèques, et greffer de l'orchestration sur quelque chose qui tient dans une seule fonction ajoute des concepts à apprendre sans aucun gain.
L'exécuter en production
Un flux peut être exposé comme un service, et c'est la partie qu'il vaut la peine de réfléchir avant d'écrire ton deuxième flux.
L'exécution est asynchrone, donc l'arrangement naturel consiste à accepter une tâche, renvoyer un identifiant et servir le résultat une fois terminé. Diffuser les événements intermédiaires permet d'afficher la progression à l'utilisateur, ce qui sur un flux de quarante secondes fait parfois la différence entre un produit qui fonctionne et une page abandonnée.
L'observabilité repose sur le fait que chaque événement peut être enregistré. Un journal qui contient tous les événements d'une exécution, avec les durées et la consommation de tokens, répond à la question de ce qui s'est mal passé sans relancer. C'est le plus grand avantage pratique de ce modèle et il mérite d'être utilisé dès le premier jour plutôt qu'après le premier incident.
Définis des timeouts et des plafonds de coût au niveau du flux. Une seule étape qui appelle un modèle en boucle peut faire des dizaines de requêtes avant que quiconque le remarque, et un plafond est ici le seul mécanisme qui fonctionne sans ton attention.
Réfléchis à ce qui arrive à une exécution à moitié terminée quand tu déploies une nouvelle version du code. Si des étapes ont été renommées ou si des événements ont changé de champs, l'état sauvegardé ne correspond plus au nouveau flux et la reprise échoue. La réponse la plus simple est d'attendre la fin des exécutions en cours avant de déployer, ce qui suffit généralement avec des flux courts. Avec des flux qui attendent de nombreuses heures une décision humaine, les formes des événements doivent être versionnées, comme un schéma de base de données.
Erreurs courantes
La première est de garder tout l'état dans le contexte plutôt que dans les événements. Le flux cesse alors de montrer les dépendances entre étapes, et c'était le principal bénéfice de ce modèle.
La deuxième est l'absence de timeout lors de la collecte de résultats concurrents. Un seul événement qui n'arrive jamais suspend toute l'exécution jusqu'à l'expiration de la limite.
La troisième est de garder les points de contrôle dans la mémoire du processus. Ils disparaissent avec le redémarrage d'un déploiement, donc la production a besoin d'un stockage durable.
La quatrième est de confier un processus entier à un seul agent avec une douzaine d'outils ou plus. Décris les étapes connues comme un flux, car tu gagnes en répétabilité et en diagnostic moins coûteux.
La cinquième est de sauter l'enregistrement des événements. Le modèle événementiel te donne gratuitement une piste d'audit, et ne pas l'utiliser gaspille le plus grand avantage de cette bibliothèque.
La sixième est de supposer que la bibliothèque exige le reste de l'écosystème. Le paquet est autonome et fonctionne sans la couche de récupération de documents.
FAQ
Ai-je besoin de tout LlamaIndex ?
Non. Workflows est un paquet autonome avec son propre dépôt et sa propre trajectoire de développement, installé séparément. Les classes d'agents prêtes à l'emploi viennent de l'écosystème plus large, tandis que le mécanisme d'étapes et d'événements lui-même fonctionne sans lui.
En quoi diffère-t-il de LangGraph ?
Par le concept qui décrit le flux. LangGraph construit un graphe de nœuds et d'arêtes, ici tu as des étapes qui écoutent des événements. Un graphe convient à une machine à états explicite, les événements conviennent à une forte concurrence et à un processus qui grandit par de nouvelles réactions.
Un flux interrompu peut-il être repris ?
Oui, mais l'écriture est à ta charge. Il n'y a pas de checkpointer intégré : après chaque étape, le moteur émet un événement interne qui porte un instantané de l'état, et tu persistes le contexte sous forme de dictionnaire et le reconstruis à la reprise. Prévois un stockage durable pour ces enregistrements, et souviens-toi qu'une étape interrompue en cours de route s'exécutera à nouveau.
Fonctionne-t-il en dehors de Python ?
La bibliothèque centrale existe aussi dans une variante TypeScript, même si l'écosystème autour de Python est nettement plus riche. Sur un projet entièrement construit sur des technologies de navigateur, vérifie le périmètre de cette variante avant de décider.
Quand ne vaut-il pas la peine de l'utiliser ?
Pour un processus qui est une séquence de deux ou trois appels au modèle, sans branchement et sans besoin de reprise. Du code ordinaire est alors plus court, moins cher et plus lisible que n'importe quelle bibliothèque d'orchestration.
La documentation se trouve sur le site du projet, et le paquet dans le registre PyPI.