Recettes agent : séquences canoniques

Cette page s'adresse à un agent connecté en MCP (ou à l'opérateur qui le pilote) qui connaît déjà les outils un par un et cherche l'ordre éprouvé pour les appeler. Chaque appel renvoie l'enveloppe { success, data } décrite dans la référence agent ; les séquences 1 et 2 ci-dessous sont les deux surfaces d'entrée légales. Chaque séquence donne ses préconditions, les appels numérotés avec leurs paramètres clés, ce que vous devez observer, et où regarder quand un appel refuse.

Aucune séquence de ce livre de recettes ne fait atterrir quoi que ce soit toute seule : chaque chemin se termine sur un gate ou une acceptation, et un proposeur n'approuve jamais sa propre proposition.

Créer, publier, invoquer

La boucle d'authoring complète : d'un draft vide à une mission neuve qui exécute votre graphe.

Préconditions — accès MCP tenant-admin ; un modèle et un provider que vous avez le droit de lier (aucun fallback silencieux à l'invocation).

Étapes

1. workflow_catalog — lisez d'abord la palette : 138 types de nodes répartis en 17 catégories, chacun avec ses pins. Ne câblez que des connexions compatibles pin à pin ; les types de nodes au cycle de vie Legacy sont bloqués à la publication dans les nouveaux drafts.
2. workflow_create_draft — passez votre payload de graphe en graphJson (un squelette minimal suffit) ; vous recevez un id et un workflowId à l'état Draft, le seul état éditable. Il n'y a pas de paramètre de nom ici — définissez le nom d'affichage à part, avec workflow_rename.
3. workflow_update_draft — envoyez les nodes et les câblages ; répétez autant que nécessaire tant que la version est un draft.
4. Graphes gouvernés uniquement : workflow_materialize injecte les nodes de contrôle requis dans votre draft — de façon déterministe, avant la publication — relisez-les donc comme n'importe quel node que vous avez écrit. Utilisez workflow_waive_control avec une raison écrite pour un contrôle qui peut être levé ; certains contrôles ne peuvent pas l'être. Voir Gouvernance.
5. workflow_validate_draft — un essai à blanc du même validateur que la publication. Il agrège tous les problèmes dans une seule réponse : corrigez tout, puis revalidez — ne corrigez pas un problème à la fois en réessayant.
6. workflow_publish — fige le graphe en une version immuable et checksummée (SHA-256). Un renommage ultérieur reste hors du checksum. Voir ce que la publication fige.
7. workflow_invoke — passez une version explicite (≥ 1 : une version publiée, jamais un draft), vos paramètres de run (liés à la compilation), et model + provider (requis sauf si les défauts du tenant les résolvent) — ou liez un preset nommé avec presetId à la place, le levier que cet écosystème préfère à un modèle brut (référence agent). L'invocation crée une mission neuve autour du run.
8. Observez : mission_get pour l'état de la mission, workflow_run_nodes pour l'avancement node par node, decision_list pour les gates en attente d'une décision.

Sorties attendues — un workflowId ; un numéro de version publiée ; un id de mission neuf issu de l'invocation ; des gates qui arrivent comme décisions pendant l'exécution.

En cas de refus — les problèmes de validation (dominance des gates, reconvergence de branches, un node Legacy, …) arrivent tous d'un coup sous VALIDATION_ERROR ; toute édition d'une version non-draft renvoie CONFLICT ; l'invocation refuse quand le workflow n'est pas invocable. Causes et remèdes : Refus et modes d'échec.

Lancer un run sur une mission existante

La boucle d'acceptation : démarrez un run sur une mission qui existe déjà, résolvez ses gates, puis acceptez ou écartez ce qu'il propose.

Préconditions — une mission existante, planifiée et non terminale ; un workflowId et une version publiés ; aucun run déjà ouvert sur la mission — sauf compétition délibérée via un groupId partagé.

Étapes

1. mission_run_start — missionId, workflowId, version, paramètres ; groupId optionnel. Omettez groupId pour le comportement strictement séquentiel. Seul Started signifie qu'un run existe — traitez les 11 statuts de démarrage.
2. Interrogez mission_run_get jusqu'à ce que le run atteigne Proposed. Pendant l'exécution, les gates se parquent en décisions : listez-les avec decision_list, résolvez-les avec decision_respond — approve reprend l'étape, skip l'annule, fail la fait échouer. Vous n'approuvez jamais une proposition que vous avez vous-même levée.
3. Décidez. mission_run_accept : sur Accepted, exactement un changement atterrit sur la branche de la mission, et mission_run_get porte désormais les ancres de seal et isAnchored. L'acceptation est physique et fail-closed : si aucun backend de validation n'est joignable dans votre environnement, l'accept renvoie ValidationRefused et rien ne merge — le run reste Proposed. Sur StaleRefused, le tip a bougé entre-temps : démarrez un run neuf depuis le nouveau tip ; ne réessayez jamais en boucle. Ou mission_run_discard : rien n'a atterri, rien à défaire. Les 7 jetons : statuts d'acceptation.
4. mission_changement_stack — la pile ordonnée de tout ce qui a été accepté jusqu'ici ; la MR de la mission est cette pile composée. Voir changements.
5. Pour défaire un run accepté : mission_revert_preview d'abord — il montre la cascade transitive des dépendants — puis mission_revert, qui revert en ordre ordinal inverse et échoue fermé en cas de conflit : la cascade s'interrompt proprement et nomme le membre fautif ; rien de partiel n'atterrit.

Variante compétition — démarrez plusieurs runs avec le même groupId depuis le même tip (workflows, paramètres ou instructions de node différents). Acceptez celui que vous gardez ; les autres sont rejetés et leurs branches supprimées ; un accept ultérieur dans le groupe renvoie GroupAlreadyWon.

Sorties attendues — un id de run ; l'issue Proposed → Accepted ou Rejected (issues de run) ; un ordinal de changement par run accepté.

En cas de refus — 10 jetons de démarrage non-Started et 6 jetons d'acceptation non-Accepted, chacun avec son remède : Refus et modes d'échec.

Cloner un template système

Préconditions — rien au-delà de l'accès MCP ; vous clonez dans votre propre tenant.

Étapes

1. workflow_system_list — les 22 templates intégrés.
2. workflow_system_get — inspectez le graphe avant de cloner ; moins coûteux que cloner juste pour regarder.
3. workflow_clone_from_system — vous recevez un draft neuf qui vous appartient. Le clonage ne publie jamais.
4. Continuez comme dans la séquence 1, étapes 3 à 6 : éditer, valider, publier.

Les templates sont représentationnels : le clonage vous donne le graphe pour en faire le vôtre, pas un branchement sur le flux que la plateforme exécute en interne. Voir Templates système.

Sorties attendues — un nouveau workflowId à l'état Draft, entièrement éditable.

En cas de refus — le clonage lui-même refuse rarement ; les problèmes hérités remontent à workflow_validate_draft, tous d'un coup — Refus et modes d'échec.

Composer par référence

Préconditions — un draft ouvert en édition ; le sous-workflow à embarquer possède une version Published — seules les versions publiées se résolvent.

Étapes

1. workflow_tile_catalog — les tiles publiées que vous pouvez embarquer, y compris les blocs sys-.
2. Placez un node FlowRef via workflow_update_draft. Les pins tunnel de l'enfant se projettent sur la tile ; l'enfant partage votre run et votre acceptation — de la composition, jamais une surface d'invocation séparée.
3. Avant d'archiver un workflow que d'autres embarquent peut-être : workflow_referenced_by. L'archivage est refusé tant que la liste n'est pas vide.
4. workflow_rebind_flowref — déplacez un consommateur vers une autre cible. Le rebinding invalide la ratification des gates : les gates concernés doivent être ré-approuvés.

Sorties attendues — un draft dont le FlowRef se résout à la validation ; workflow_referenced_by renvoyant les consommateurs vivants de tout flux publié.

En cas de refus — archiver avec des consommateurs vivants renvoie CONFLICT ; un FlowRef pointant vers une cible non publiée remonte à la validation. Refus et modes d'échec.

Démarrer depuis un trigger

Préconditions — une version publiée, et un moyen de sortir de la surface MCP : il n'existe pas d'outil MCP de trigger de workflow, l'enregistrement passe donc par le dashboard ou par l'API REST de la plateforme. Les triggers ne déclenchent jamais des drafts.

Étapes

1. Publiez, comme dans la séquence 1.
2. Enregistrez le trigger hors MCP — soit un humain utilise Manage triggers (« Gérer les déclencheurs ») sur le workflow dans la liste des workflows du dashboard, soit vous appelez l'endpoint REST des triggers. Choisissez l'un des trois genres : Schedule (« Planification » — une expression cron), Webhook (l'endpoint porte un secret en écriture seule — stockez-le à la création, vous ne pourrez pas le relire), ou Event (« Événement » — l'un des six seams actifs : mission.created, conversation.completed, support-case.created, incident.created, batch.completed, mr.merged).
3. Choisissez la politique de version : LatestPublished suit la dernière version publiée ; Pinned reste sur celle que vous nommez. selectedModel et selectedProvider sont obligatoires sur le trigger.
4. Vérifiez un déclenchement : workflow_runs pour les runs du workflow, puis mission_get et decision_list sur la mission créée par chaque déclenchement.

Chaque déclenchement se comporte comme un workflow_invoke : une mission neuve, le même graphe, les mêmes gates. Les triggers ne contournent jamais les gates — un run déclenché se met en pause aux mêmes décisions qu'un run manuel.

Sorties attendues — une nouvelle mission par déclenchement ; les runs visibles via workflow_runs.

En cas de refus — un trigger pointant vers un workflow archivé ou jamais publié ne peut pas se déclencher ; l'omission du modèle ou du provider refuse à l'enregistrement. Refus et modes d'échec.