Workflows d’instruction
En mots simples : un workflow est un processus écrit sous forme d’étapes nommées. Chaque étape dit ce qui se passe (un agent rédige, un outil est appelé, une personne décide) et quelles étapes doivent se terminer avant elle. Les deux premières sections montrent toute l’idée ; le reste est le langage complet, pour le jour où vous en aurez besoin.
Ceci est une traduction de la référence issue de la spécification. Le texte anglais fait foi ; les mots-clés, les noms de champs et les exemples sont laissés tels que dans l’original.
Dialecte : instruction/workflow. Révision : 1.
État : brouillon de travail de la première édition. C’est une partie native d’instruction.md.
Date : 2026-10-28.
Les workflows d’instruction (Instruction Workflows) décrivent des processus réutilisables sous forme d’étapes nommées et typées. Le langage comprend les déclencheurs, le flux de données, les appels de modèles et d’outils, les routes conditionnelles, le travail en parallèle, les décisions humaines, les attentes durables, la reprise et les résultats finaux. AgentD a apporté le langage initial ; il est désormais spécifié ici indépendamment de tout environnement d’exécution. Une implémentation annonce les types de nœuds qu’elle prend en charge, ainsi que ses capacités d’expression, d’identité, de stockage et d’intégration.
Le schéma de workflow et le registre des nœuds sont des parties normatives de cette référence, lisibles par machine. Le registre conserve les 74 types importés, dont les 11 types de déclencheurs. La validation par le schéma n’est qu’un niveau de validation ; les exigences ci-dessous sur le graphe et le comportement s’appliquent aussi. Un moteur de rendu n’est pas un hôte de workflows.
Déclarer un workflow
:::workflow{id=brief dialect="instruction/workflow"}
name: morning-brief
steps:
start:
kind: manual
draft:
kind: agent
depends_on: [start]
instruction: Prepare a concise daily brief. Preserve uncertainty.
review:
kind: human
depends_on: [draft]
question: Accept this brief?
schema: { type: string, enum: [accept, revise] }
route:
kind: switch
depends_on: [review]
on: "{{ steps.review.output }}"
cases: { accept: accepted, revise: revision }
accepted:
kind: finish
depends_on: [route]
output: "{{ steps.draft.output }}"
revision:
kind: finish
depends_on: [route]
status: cancelled
reason: The reviewer requested a revision.
:::
L’id extérieur est l’identité d’un objet de l’instruction ; name est
l’identité du workflow au sein de son hôte. dialect sélectionne ce contrat.
YAML et JSON sont des représentations équivalentes du même modèle. Les clés en
double dans un mappage sont des erreurs. Le corps structuré d’un workflow est
littéral : les directives Markdown et les substitutions ${parameter} de
l’instruction ne s’y activent pas. Les modèles de workflow {{ … }} ont le sens
décrit plus bas.
Ouvrir, analyser, résoudre, compiler ou afficher l’instruction MUST NOT (ne doit pas) armer des déclencheurs, enregistrer des outils, exposer des routes, envoyer des messages ni démarrer une exécution. L’activation est une opération explicite de l’hôte, après validation et autorisation.
Champs de la définition
| Champ | Signification |
|---|---|
name |
Identifiant obligatoire, de 1 à 64 caractères, conforme à [A-Za-z_][A-Za-z0-9_-]* |
steps |
Mappage obligatoire des identifiants d’étapes vers des définitions typées |
description |
Objectif, lisible par une personne ; peut aussi servir de description d’outil enregistré |
armed |
Indique si une définition explicitement activée peut armer ses déclencheurs ; true par défaut |
inputs.schema, outputs.schema |
Schémas des entrées de l’exécution et du résultat final |
concurrency |
max_runs, on_overflow (queue, drop, replace) et scope (workflow, key) |
key |
Modèle évalué au déclenchement, qui identifie l’entité concernée par une exécution ; obligatoire pour la concurrence par clé |
limits |
Étapes, jetons, échéance et budget par exécution |
priority |
low, normal ou high ; une préférence d’ordonnancement, jamais l’octroi d’une permission |
durable |
Indique si l’état de l’exécution survit au processus de l’hôte ; false autorise explicitement les exécutions en mémoire seule |
state |
Schémas déclarés des variables d’exécution et réducteurs des écritures concurrentes |
unload |
Politique de retrait : drain, cancel ou detach, avec un délai facultatif |
tool |
Interface proposée de workflow appelable : nom, mode synchrone ou asynchrone et droits accordés aux appelants |
act_for |
Principal délégué proposé et mécanisme de consentement ; l’approbation de l’opérateur est requise |
Les champs standard inconnus et les noms de types inconnus sont des erreurs. Les
champs à espace de noms x-* peuvent porter des données d’extension déclarées.
Un hôte MUST (doit) signaler une extension non prise en charge qui modifie le
comportement, plutôt que de l’écarter en silence. Les directives de
configuration qui chargent un fichier, une URL, un dossier ou une ressource MCP
relèvent de la configuration de l’hôte ; ce ne sont pas d’autres définitions de
workflow.
Les entrées sont validées avant l’admission. Des entrées invalides ne créent
pas d’exécution. Les résultats terminés doivent respecter outputs.schema ; un
échec de schéma n’est pas une fin réussie. Les limites de ressources et
l’admission au titre de la concurrence doivent être consignées dans le profil
d’exécution, afin que le résultat puisse être examiné.
Graphes, portées et validation
Le graphe des dépendances est acyclique. Les identifiants d’étapes sont uniques
au sein d’une portée. Chaque étape de premier niveau doit être atteignable
depuis un déclencheur, par des dépendances ou des arêtes de routage explicites.
Un graphe de premier niveau a besoin d’au moins un déclencheur et d’un finish.
Les noms de dépendances, les cibles d’aiguillage, les cibles d’erreur et les
cibles de délai dépassé doivent exister dans la même portée. Les valeurs des cas
d’un aiguillage nomment une seule étape, sous forme de chaîne, et non une
liste.
foreach, batch, iterate et subgraph contiennent body: {steps: …}.
parallel et race contiennent des branches nommées, chacune avec ses
propres steps. Les dépendances à l’intérieur d’un corps nomment des étapes
voisines. Les portées imbriquées ne peuvent contenir ni déclencheurs ni
finish ; leur résultat est celui de leurs étapes terminales. L’imbrication
maximale est de quatre niveaux de corps, et les définitions de premier niveau
contiennent au plus 512 étapes. Les identifiants d’instance générés désignent
l’itération ou la branche, par exemple each[0].draft,
parallel{research}.fetch ou sub.review.
Une implémentation doit valider les types, les champs obligatoires propres à chaque type de nœud, les portées, les références, l’atteignabilité, les cycles, les capacités d’expression et les limites avant l’activation. Le JSON Schema laisse volontairement ouvertes certaines valeurs de données d’adaptateur ; il ne valide ni les arguments d’un outil distant, ni tous les chemins d’expression, ni l’autorisation, ni le comportement à l’exécution. Ces vérifications exigent les contrats de l’hôte et des intégrations concernés. Un type obligatoire non pris en charge est une erreur, pas une opération sans effet.
Déclencheurs
Le registre comprend once, manual, loop, schedule, subscribe,
stream, correlate, signal, event, a2a et webhook.
Un déclencheur produit un événement soumis à l’admission, plutôt que
d’effectuer directement le travail en aval. Ses données deviennent le résultat
de l’étape du déclencheur qui s’est activé. Une exécution active exactement un
déclencheur ; les déclencheurs voisins passent à skipped et satisfont les
dépendances. Les mappages inputs d’un déclencheur utilisent les espaces de
noms payload et env du moment du déclenchement ; les entrées d’exécution
obtenues sont vérifiées par rapport à inputs.schema.
schedule accepte cron, every ou at, avec exactement une source de
temps. Le dialecte cron à cinq champs, hérité, est en UTC. Il ne reçoit pas de
champ tz implicite : une récurrence selon le calendrier local peut utiliser le
dialecte de planification explicite du bloc schedule, distinct. Les hôtes
consignent la politique appliquée aux déclenchements manqués et à la reprise.
loop combine intervalle, délai et temporisation croissante avec des conditions
d’arrêt et un nombre maximal d’itérations. once et manual distinguent
l’activation automatique d’une exécution demandée par un opérateur.
subscribe lit une ressource MCP nommée après des notifications de changement
et peut appliquer un anti-rebond (debounce), filtrer et recueillir une fenêtre
d’échantillons bornée. stream consomme des événements persistés, avec un
filtrage par sujet, des décalages et des réglages de débit et de lots.
correlate regroupe des événements liés dans une fenêtre bornée, avec un
plafond sur l’état en attente. signal est une notification déclenchée sur
front : les étapes déjà en attente la reçoivent, et un signal envoyé avant
l’enregistrement d’une attente n’est pas mis en mémoire tampon. Utilisez un flux
persisté quand la conservation est nécessaire. Les événements et les abonnements
exigent une capacité explicite de l’hôte et des liaisons authentifiées à leurs
sources.
a2a lie des commandes acceptées, des rôles de principaux et un schéma
d’entrée. webhook décrit un chemin entrant, des méthodes, l’authentification,
le débit et la politique de réponse. Déclarer l’un ou l’autre ne crée jamais
d’écouteur non authentifié. L’hôte les autorise et les lie pendant l’activation.
Champs communs aux étapes
Chaque étape a un kind. Les champs communs sont depends_on, description,
when, timeout, retry, on_error, on_replay, idempotent,
output_schema, budget, cache, skills et otel. Leur existence ne
signifie pas qu’un hôte prend en charge chaque nœud ou chaque intégration.
timeout borne une tentative ou une attente propre au nœud. retry.max compte
les nouvelles tentatives après la première, vaut entre zéro et vingt, et
retry.backoff donne le délai exponentiel initial. La temporisation est
durable, avec une croissance bornée et une variation aléatoire. on_error vaut
fail (par défaut), continue ou goto:<step>.
on_replay vaut retry (par défaut), skip ou fail. Un hôte consigne dans
son profil d’exécution les valeurs par défaut et les contraintes effectives de
modèle, d’outils, de réseau et de budget.
Les champs des nœuds réseau peuvent en outre déclarer breaker: {failures, cooldown},
rate et idempotency. Les nouvelles tentatives traitent l’échec d’une
tentative ; les disjoncteurs (breakers) partagent l’état de panne entre les
exécutions ; les réglages de débit reportent le travail sans consommer de
tentative ; l’idempotence rend reconnaissable une livraison répétée. Ces
mécanismes ont des sens différents et MUST NOT (ne doivent pas) être ramenés à
un seul compteur de tentatives.
Modèles et expressions
Une chaîne composée d’exactement un {{ path }} donne la valeur typée
référencée. Une chaîne avec du texte autour interpole : elle conserve les
chaînes et encode les autres valeurs en JSON. {{ path | fallback }} fournit
une valeur de repli uniquement pour un chemin absent ; un null existant
n’utilise pas la valeur de repli. Un / initial sélectionne un chemin JSON
Pointer, utile pour les identifiants générés qui contiennent des points. Un
chemin absent sans valeur de repli fait échouer la tentative.
| Espace de noms | Signification |
|---|---|
inputs |
Entrées d’exécution validées |
run |
Identité de l’exécution et du workflow, début, principal, tâche, tentative et état |
steps.<id> |
État, résultat, erreur et tentative d’une étape ; dans un corps, identifiants des étapes voisines |
vars |
Variables d’exécution déclarées ou écrites |
env |
Contexte de l’hôte et de l’exécution ; pour chaque étape, step, attempt et un idempotency_key stable |
memory |
Clés de mémoire durable explicitement liées |
item, index, alias as |
Élément courant de la collection et son index |
batch, iteration, branch |
Contexte d’exécution imbriqué |
CEL: … évalue une expression CEL. La garde when, les conditions
d’assertion, les expressions map/filter/reduce, les conditions d’itération et
les filtres d’abonnement utilisent leurs contextes d’évaluation documentés. Les
body et branches imbriqués, les schémas, les mappages de cibles d’aiguillage
et les champs porteurs d’expressions restent littéraux jusqu’à ce que leur
propre nœud les évalue. Un hôte dépourvu d’une capacité CEL requise doit refuser
l’activation. Il ne peut pas remplacer l’expression par « vrai ».
when peut aussi utiliser {noul: "statement", state?, model?, confidence?}
pour une décision appuyée sur un modèle. L’hôte représente cette décision comme
une étape <id>.when durable et dotée d’un budget. Une réponse incertaine ou
d’une confiance insuffisante fait échouer la garde. Le seuil de décision
effectif doit être explicite dans le profil d’exécution. Une condition de règle
écrite en prose dans l’instruction environnante est distincte de cette garde de
workflow exécutable.
Les marqueurs de secrets tels que {{secret:NAME}} et {{secret-file:PATH}} ne
sont résolus que dans les champs d’intégration autorisés qui portent des
identifiants. Ailleurs, ils restent littéraux. Les secrets ne deviennent ni un
résultat d’étape ordinaire, ni des métadonnées du document, ni du contenu de
journal. La résolution de l’instruction ne lit pas le coffre de secrets de
l’hôte.
Embranchements et jonctions
Un when faux au premier niveau ou une route d’aiguillage non choisie rend une
étape pruned. Une étape pruned ne satisfait pas les dépendances. Une étape
dont tous les chemins entrants sont pruned l’est aussi ; au moins un chemin
vivant maintient une jonction éligible. Une étape skipped, elle, satisfait les
dépendances. Cette distinction permet de joindre des branches inégales.
Une route d’aiguillage sélectionnée, on_error: goto:… ou on_timeout peuvent
activer leur cible sans attendre la liste de dépendances de cette cible, mais ne
peuvent pas contourner sa garde when. Les arêtes de routage peuvent revenir
sur une étape ; le graphe des dépendances doit toujours être acyclique et
l’exécution reste bornée par ses limites. Une route de reprise dont la garde
échoue n’efface pas l’échec d’origine.
Dans un corps, un when faux produit skipped, ce qui permet aux étapes
voisines suivantes de se poursuivre. Les cas d’aiguillage non choisis dans les
corps restent, eux, pruned. Les hôtes et les outils de visualisation doivent
préserver cette différence au lieu de présenter tous les nœuds inactifs comme
équivalents. Une image Mermaid ne peut pas redéfinir ce comportement.
Travail parallèle, répété et délégué
parallel exécute des branches nommées ; race retient le premier résultat
recevable et annule le travail des perdants. foreach exécute un corps par
élément, avec une taille de batch, un parallélisme et un débit bornés. batch
donne un groupe à chaque corps. iterate répète selon while/until, avec un
nombre maximal d’itérations. La politique de collecte est explicite, par
collect. Un corps ne peut pas hériter en silence d’une multiplication non
bornée.
workflow appelle un enfant nommé en mode sync, async ou detached ; async
renvoie un descripteur. join attend des descripteurs selon une politique de
délai, de minimum et de résultats partiels. cascade contrôle l’annulation des
enfants. subagent délègue un travail borné avec des outils, des serveurs, des
compétences, un contexte et des budgets explicites. Les nœuds A2A lient des
pairs nommés, des contrats de tâches et de messages, et des attentes
d’achèvement. La délégation peut restreindre l’autorité ; déclarer un enfant ne
doit pas élargir les permissions effectives de l’appelant.
Attentes et décisions humaines
wait, sleep, human, les attentes d’enfants et les temporisations entre
tentatives suspendent le travail au moyen d’enregistrements d’attente durables,
plutôt que par un fil bloqué en mémoire. Une attente peut nommer une ressource,
un événement, un signal, une exécution, un sous-agent, une conversation, un
webhook, une tâche ou une autre condition d’attente enregistrée. on_timeout
est une cible de routage explicite. Une étape de décision humaine nomme une
question, un schéma de réponse facultatif et le destinataire prévu. Les réponses
sont validées et liées à un principal autorisé ; afficher une pastille
d’approbation ou cocher une case dans la documentation n’est pas une
approbation.
Une implémentation qui revendique une exécution durable doit restaurer les attentes suspendues et leurs échéances. Elle doit distinguer une déclaration enregistrée d’une exécution active, et un point de sauvegarde posé par l’auteur d’une décision humaine consignée.
États des exécutions et des étapes
Les états d’une exécution sont running, paused, completed, failed,
refused, cancelled et stalled. Les deux premiers ne sont pas terminaux. Un
finish détermine l’état et le résultat finaux ; n’avoir ni travail prêt, ni
travail en cours, ni finish donne stalled, ou failed quand une erreur en
amont a causé le blocage.
Les états d’une étape sont pending, running, suspended, done, skipped,
pruned, failed, timeout et cancelled. Seuls done et skipped
satisfont une dépendance ordinaire. Une erreur sous on_error: continue termine
l’étape avec l’erreur consignée. Mettre fin à une exécution annule les étapes
inachevées. Les codes de sortie, les systèmes de persistance et les protocoles
clients relèvent des adaptateurs de l’environnement d’exécution, et non d’une
nouvelle syntaxe Markdown.
Durabilité, idempotence et mises à jour
Une étape à effet enregistre un point de sauvegarde running avant l’effet. Les
étapes de données déterministes peuvent être rejouées depuis le point de
sauvegarde précédent. Après une panne, un effet achevé à distance mais dont
l’accusé de réception a été perdu peut être livré de nouveau. Le contrat est une
livraison au moins une fois ; ce n’est pas une exécution distante exactement une
fois.
La clé d’idempotence par défaut est formée des 32 premiers caractères
hexadécimaux de sha256(run_id + "." + step_instance_id), stable d’une
tentative ou d’une relecture à l’autre pour cette instance. Une clé métier
déclarée peut dédupliquer entre exécutions. Les outils et services distants
doivent réellement respecter la clé pour que la déduplication ait lieu.
on_replay détermine si un travail incertain est retenté, ignoré ou mis en
échec. Un hôte ne doit pas se dire sûr à la relecture du seul fait qu’une clé a
été envoyée.
Une exécution consigne l’empreinte de sa définition et le profil d’exécution.
Mettre à jour une définition en ligne touche les admissions suivantes ; les
exécutions existantes gardent leur définition épinglée. La restauration exige la
définition correspondante et ne doit pas lui substituer le texte le plus récent.
Le retrait applique unload et consigne l’annulation ou la fin du travail
entamé. La mémoire, les artefacts, les décalages de flux et les points de
sauvegarde des déclencheurs ont des durées de vie distinctes. Les artefacts
sensibles conservent les contrôles d’accès de l’hôte et ne sont pas copiés en
silence dans les paquets d’instructions.
Catalogue des nœuds et points d’extension
La référence des nœuds complète est générée à partir du registre natif et énumère les champs obligatoires et facultatifs de chaque type importé. Elle couvre les déclencheurs, le contrôle du flux, les transformations de données, la mémoire, les artefacts, les connaissances, la recherche, MCP, HTTP, A2A, la messagerie, le cycle de vie des workflows, les opérations de modèles, les agents et les décisions humaines. Les fournisseurs de nœuds peuvent être des intégrations distinctes de l’hôte ; figurer dans le langage ne promet pas qu’un hôte dispose d’un compte ou d’une implémentation.
Les hôtes de workflows publient un profil de capacités : types de nœuds, fonctions d’expression, bornes de ressources, liaisons d’identifiants et d’identité, prise en charge de la durabilité. Un comportement personnalisé passe par des extensions déclarées, à espace de noms, avec des exigences explicites de schéma et de capacités. Un comportement exécutable inconnu ne doit jamais se rabattre sur l’exécution d’une approximation. Les moteurs de rendu préservent la source et montrent visiblement la sémantique non prise en charge ; un usage limité au rendu peut rester utile sans environnement d’exécution.
Un nœud personnalisé utilise kind: alias:node. Sa liaison d’extension, dans
l’instruction qui l’entoure, sélectionne un manifeste et une version exacts ; un
workflow autonome reçoit des liaisons équivalentes du profil de son hôte.
provides.workflow_nodes, dans le manifeste de l’extension, associe les noms de
nœuds à un role (trigger ou step), à un schema de nœud, à un contrat
semantics et à des capacités requires facultatives. Le schéma de workflow de
base peut conserver le nœud à espace de noms, mais l’activation valide en plus
ce manifeste et son fournisseur installé. Les métadonnées de la source
n’installent jamais de code et n’autorisent jamais un fournisseur. Le
vérificateur de graphes natif et borné du dépôt rejette ces nœuds comme non pris
en charge, plutôt que de revendiquer la conformité d’un hôte d’extensions.
Migration et provenance
Le registre initial et les champs communs ont été importés, à la demande du
propriétaire, depuis l’instantané du schéma AgentD dont le SHA-256 est
40f1d4a06967af70705d1b6aa508ebcc7defc7693ad3e8d8570eb02637ac5f23.
L’instantané exact est conservé dans la provenance amont.
Le schéma d’instruction.md ajoute des vérifications de champs par type et une
structure de corps récursive explicite. Les vérifications du graphe et du
comportement restent séparées.
agentd/workflow reste un identifiant de compatibilité d’adaptateur. Les
nouveaux documents natifs utilisent instruction/workflow ; le profil AgentD
peut exporter des définitions compatibles vers AgentD sans réécrire les données
de leurs étapes. Cette migration n’a modifié aucune installation d’AgentD,
aucune configuration de serveur, aucun site publié ni aucun environnement
d’exécution. Ce brouillon de travail et ses nouveaux cas de conformité exigent
encore un examen indépendant d’une implémentation d’exécution avant une
publication finale.