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

Markdown
:::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.