Référence agent : outils workflow & run

Cette page est la surface de référence des 33 outils MCP qui créent, exécutent et acceptent les workflows : 23 outils workflow_*, 3 outils workflow_node_instructions_* et 7 outils mission-run/changement, en huit groupes. Pour les procédures pas à pas, utilisez les recettes ; quand un appel refuse, la page des refus associe chaque token à sa récupération.

À qui s'adresse cette page

Vous êtes un agent connecté en MCP — ou l'opérateur qui le pilote. Chaque outil de cette page renvoie la même enveloppe : { success, data } en cas de succès, { success: false, error, code } en cas de refus. Tous ces outils exigent des droits tenant-admin ; si un appel échoue à l'autorisation, c'est un problème de permissions, pas un problème de workflow.

Cette page dit ce que fait chaque outil et ce qu'il renvoie. Pour la mécanique sous-jacente — compilation, branches, seals — lisez le chapitre d'architecture des workflows.

Les deux surfaces d'entrée légales

Un workflow publié ne s'exécute que par deux surfaces : workflow_invoke et mission_run_start — tout le reste de cette page crée, inspecte ou accepte.

• workflow_invoke — workflow d'abord. Compile une version publiée en une mission neuve qu'il crée pour vous. À utiliser quand le travail n'a pas encore de mission.
• mission_run_start — un run sur une mission existante. Le run reçoit sa propre branche à partir du tip de la mission et entre dans la boucle d'acceptation : né Proposed, puis vous l'acceptez ou l'écartez. À utiliser quand le travail appartient à une mission que vous avez déjà.

Le parcours côté humain de cette boucle est Runs, acceptation et changements.

Création et cycle de vie (9 outils)

Ces outils mènent un graphe du draft vide à la version publiée gelée. Les drafts sont le seul état éditable ; publier gèle le graphe — voir Cycle de vie d'un workflow.

Composition (3 outils)

Les workflows se composent par référence : un node FlowRef intègre un autre workflow publié comme sous-workflow.

Découverte et observation (6 outils)

Exécution (1 outil)

workflow_invoke — exécuter une version publiée, workflow d'abord.

• Entrées : workflowId, version (doit être ≥ 1 — exécuter « la dernière, quelle qu'elle soit » n'est jamais implicite), optionnels objective, model, provider, paramsJson, projectId, presetId (+ forceOnAllCallSites), agentBudgetJson (+ forceBudgetOnAllAgentSites).
• Les paramètres se lient à la compilation. Les valeurs de paramsJson sont liées quand le graphe est compilé en plan de la nouvelle mission ; rien ne se relie en cours de run.
• La résolution du modèle est explicite. model et provider sont requis sauf si les défauts du tenant les résolvent — il n'y a pas de repli silencieux de modèle.
• Les presets sont le levier à préférer. presetId exécute cette invocation avec un preset nommé plutôt qu'un model brut ; un preset inconnu refuse avec NOT_FOUND au lieu de se replier. Par défaut, il ne remplace que le preset par défaut du workflow — un step qui a épinglé son propre preset à l'édition le garde — sauf si vous passez aussi forceOnAllCallSites.
• Budgets d'agent par run. agentBudgetJson ajuste les budgets d'agent pour ce run uniquement, axe par axe. Par défaut, un axe indiqué ne se substitue qu'au défaut moteur — il ne comble que les axes que le budget rédigé par le step laisse non renseignés, et un step qui a rédigé cet axe garde sa propre valeur — sauf si vous passez aussi forceBudgetOnAllAgentSites, qui impose les axes indiqués à chaque site agent, au-dessus de ce que le step a rédigé. Une surcharge malformée refuse avec VALIDATION_ERROR avant toute création de mission.
• Le ciblage de projet est explicite et échoue bruyamment. projectId (id ou slug) dirige les écritures du run vers un projet : une cible inconnue refuse avec NOT_FOUND et un projet non-Active avec CONFLICT, dans les deux cas avant toute création de mission. Omettez-le et le run atterrit dans le projet par défaut du tenant — enregistré comme tel dans la provenance de la mission.
• Retour : le nouveau missionId avec les comptes de steps, de gates et de contrôles. Chaque gate naît en pause derrière une décision en attente.
• Suites : mission_get pour suivre la mission, decision_list pour trouver les gates en attente, workflow_run_nodes pour le statut par node.

Clonage (2 outils)

Templates système (2 outils)

Les templates sont représentatifs : le clonage vous donne un graphe à posséder et éditer, pas un branchement sur les flux internes de la plateforme. L'énumération complète des 22 se trouve sur Templates système.

Instructions de node (3 outils)

Les nodes coder et agent peuvent porter une liaison d'instructions — un texte de surcharge qui remplace les instructions rédigées du node au prochain dispatch, sans toucher au graphe publié ni à son checksum. Une seule liaison s'applique — la plus spécifique gagne : run > project > tenant > global.

Seuls les slots définis manuellement sont modifiables par ces outils ; un slot détenu par la machinerie de prompt-engineering de la plateforme refuse avec CONFLICT. ARDS ne propose pas encore lui-même d'améliorations de prompts en v1 ; si cela arrive, les propositions arriveront comme des décisions que vous approuvez — rien ne s'appliquera jamais tout seul. Voir Gouvernance pour la vue côté humain.

Runs de mission et changements (7 outils)

La boucle d'acceptation sur une mission existante. Strict-séquentiel par défaut : un seul run non décidé à la fois, chaque run accepté atterrissant comme un changement sur la branche de la mission. Passez le même groupId à plusieurs démarrages pour ouvrir une compétition à la place — un gagnant, les autres rejetés.

Le parcours côté humain — accepter, écarter, revert, compétition — est Runs, acceptation et changements.

Contexte mission

Quatre outils voisins que vous croiserez dans chaque session workflow ; la surface mission complète est documentée dans Missions & tasks.

mission_propose rédige une mission et la route vers approbation au lieu de la créer directement — la proposition arrive comme une décision qu'un humain accepte ou rejette. Vous n'approuvez jamais votre propre proposition.

mission_create crée une mission directement. Attachez un workflow à la création, ou démarrez des runs dessus plus tard avec mission_run_start.

mission_decompose demande au planificateur de découper en tâches une mission née d'une conversation. Les missions qui portent un workflow sautent cette étape : le graphe est déjà le plan.

decision_respond est l'unique verbe de résolution de gate. Ses résolutions s'appliquent à une gate en pause ainsi : approve libère la gate une fois les steps précédents terminés ; skip annule le step gardé ; fail le fait échouer. Laisser la décision sans réponse maintient le run en pause. Les gates en attente sont listées par decision_list et apparaissent dans la file Decisions (« Décisions »).

Vocabulaires de statuts

Tables de tokens normatives. Les tokens sont renvoyés tels quels ; comparez-les exactement. Le détail de récupération par token vit dans Refus et modes d'échec.

Statuts de démarrage de run

Renvoyés par mission_run_start. Un token de succès, dix refus.

Statuts d'acceptation de run

Renvoyés par mission_run_accept. Un token de succès, six refus.

Issues d'un run

Le cycle de vie du run lui-même — les mêmes tokens que la cheatsheet des états.

Statuts de version

Les seules transitions légales sont Draft → Published → Archived.

États des nodes d'un run

Les statuts par node tels que rapportés par workflow_run_nodes et le récapitulatif de mission_run_get.