Définir le parcours avant de laisser l’agent boucler.
Nommer les états, les transitions autorisées, les gardes, les pauses et les reprises tout en laissant l’exécution au logiciel hôte.
Réponse courte
Représentez le parcours avec des états et des événements explicites avant d’ajouter les décisions du modèle. La machine déclare les états possibles, les transitions légales et les gardes à franchir. Le modèle peut choisir parmi les événements proposés à cet instant, mais l’application lit les données, appelle les modèles et exécute les outils. Des états persistés rendent les pauses, les reprises et les validations humaines visibles. XState v5 fournit cette base générale. Le paquet @statelyai/agent 2.0 l’applique aux agents, mais il est actuellement en alpha. Son API peut évoluer, sa version doit être figée et sa pertinence en production doit être évaluée séparément.
À retenir
- 01
Le modèle choisit uniquement parmi les transitions autorisées dans l’état actuel.
- 02
Les gardes protègent les transitions ; l’application exécute chaque effet externe.
- 03
@statelyai/agent 2.0 est en alpha et ne doit pas être présenté comme une dépendance stable pour la production.
01 / SITUATION
Un prompt est un mauvais endroit pour cacher un processus métier
Une boucle d’agent commence souvent par une suite de consignes : réunir le contexte, chercher, poser une question, préparer une proposition, attendre l’accord puis agir. Avec les reprises, les informations absentes, les droits refusés et les pauses humaines, cette suite devient un vrai processus dont les chemins autorisés ne se lisent plus dans un prompt.
La machine à états nomme ces chemins. L’attente n’est plus confondue avec l’échec, l’accord reste distinct de l’exécution et un événement choisi par le modèle ne peut pas sauter un contrôle obligatoire. Le parcours devient inspectable même si les réponses du modèle restent probabilistes.
02 / MECHANISM
La machine porte le parcours, l’application porte les effets
Chaque transition et chaque effet externe doivent avoir un propriétaire explicite.
- 01Nommer les états
Décrire des situations utiles : collecte du contexte, attente d’une précision, préparation, attente d’un accord, exécution, fin et échec. Éviter les états qui ne font que reproduire un chargement d’interface.
- 02Définir les événements et les passages autorisés
Lister les événements acceptés dans chaque état et leur destination. Un événement interdit à cet instant ne peut pas produire d’effet, même si le modèle le propose.
- 03Ajouter des gardes déterministes
Vérifier les champs requis, les droits, la fraîcheur et les invariants métier avant de changer d’état. Une garde s’exécute en code, pas selon l’avis du modèle.
- 04Borner les décisions du modèle
Ne lui proposer que les événements et les demandes typées autorisés maintenant. Son raisonnement libre ne doit pas lui donner de pouvoir supplémentaire sur le parcours.
- 05Exécuter dans l’application
L’application fournit les appels de modèles, les outils, les identifiants, la persistance et le réseau. Elle revérifie les droits et l’état avant chaque effet important.
- 06Persister, observer et tester
Conserver des instantanés qui permettent la reprise, tracer les transitions et tester les chemins légaux, refusés, expirés et en erreur. Évaluer l’état obtenu autant que le texte produit.
03 / Dans le travail réel
Entrée du support
La machine passe de la collecte du contexte à une demande de précision ou à la préparation du ticket. Seule une proposition confirmée peut entrer dans l’état d’envoi.
Intervention sur un équipement
Le diagnostic en lecture peut suggérer une procédure. Tout état susceptible d’affecter la machine attend un opérateur habilité et un nouveau contrôle de sécurité.
Exception financière
Le modèle classe la demande et réunit les éléments. Les gardes vérifient les champs obligatoires ; l’application ouvre ensuite la revue autorisée.
Pièges fréquents
- Cacher tout le parcours dans un prompt système et une boucle while improvisée.
- Laisser une sortie du modèle déclencher un effet externe sans transition contrôlée par l’application.
- Ajouter une transition passe-partout qui contourne les gardes lorsque l’événement est inattendu.
- Conserver les messages sans l’état nécessaire pour reprendre le parcours correctement.
- Supposer qu’une API alpha est stable parce que le principe architectural est solide.
Checklist d’implémentation
- Les états métier et les états terminaux sont nommés.
- Chaque état indique les événements qu’il accepte.
- Les gardes sont déterministes et testées séparément.
- Le modèle ne voit que les décisions et les outils disponibles à cet instant.
- L’application garde les identifiants, les effets et les contrôles de droits.
- Les pauses humaines, délais, reprises et annulations ont leurs transitions.
- Les tests couvrent les événements illégaux, l’état périmé, l’échec partiel et la reprise.
Ce que cette approche ne promet pas
- La machine encadre les chemins. Elle ne rend ni le jugement du modèle ni le résultat des outils exact.
- XState est une base stable, mais @statelyai/agent 2.0 est en alpha et peut connaître des ruptures avant sa version stable.
- Un parcours très court et limité à la lecture n’a pas forcément besoin d’une machine dédiée tant que les branches et les reprises restent simples.
Sources et nature des références
- 01Stately and XState v5 documentationStately · 2026Documentation officielle
- 02@statelyai/agent 2.0 alpha documentationStately · 2026Documentation officielle
- 03Demystifying evals for AI agentsAnthropic · 2026Pratique de terrain
Questions fréquentes
Le modèle peut-il encore planifier dans une machine à états ?
Il peut proposer du texte, des paramètres ou l’un des événements disponibles. La machine fixe les choix légaux et l’application décide de l’exécution.
Faut-il utiliser @statelyai/agent ?
Non. La même architecture peut reposer sur XState, une autre bibliothèque ou un réducteur explicite. Ce qui compte est le contrat de transition visible.
Comment représenter une validation humaine ?
Par un vrai état d’attente avec une proposition persistée, une date d’expiration et des événements distincts pour confirmer, modifier ou refuser. Le ton de la conversation ne vaut pas accord.