Blog · Guide · 29 octobre 2026

États et transitions d'un workflow AEGIS, pas à pas

Aussi en: English, Español, Português, 日本語, Deutsch, 한국어, 简体中文, Italiano, हिन्दी · Tous les guides en français

Transparence : chez 100monkeys.ai, nous développons AEGIS ; lisez donc ce guide comme le récit de son fabricant. Il a été rédigé par l'un de nos agents d'IA à partir de la documentation publique d'AEGIS (en anglais), principalement la Workflow Manifest Reference et la CLI Reference, et relu par l'entreprise ; cette version française est une traduction du guide original en anglais. Chaque ligne YAML et chaque commande ci-dessous sont copiées de ces pages ; aucune n'a été exécutée pour ce guide. Les citations restent en anglais, avec la traduction à côté. Là où la documentation laisse une question ouverte, la dernière section le dit.

AEGIS by 100monkeys.ai, in beta, exécute un workflow comme une machine à états finis écrite dans un seul fichier YAML. La référence l'appelle "a durable, restartable sequence" (une séquence durable et redémarrable) qui coordonne agents, conteneurs, commandes système et portes d'approbation humaine. Ce guide écrit un état à la fois et montre comment le moteur choisit le suivant.

Étape 1. Écrire l'en-tête

apiVersion: 100monkeys.ai/v1
kind: Workflow

metadata:
  name: dev-pipeline
  version: "1.0.0"

apiVersion doit valoir exactement 100monkeys.ai/v1 et kind exactement Workflow. name suit ^[a-z0-9][a-z0-9-]{0,62}$, et le couple nom et version doit être unique : écraser une version existante demande le paramètre force. metadata.input_schema est facultatif ; s'il est présent, l'entrée de l'appelant est validée avant le lancement, et une charge invalide est "rejected with HTTP 422; no workflow execution is created." (refusée avec HTTP 422 ; aucune exécution de workflow n'est créée.)

Étape 2. Nommer le premier état et les limites

Sous spec, initial_state est obligatoire et doit exister dans spec.states. Deux limites arrêtent une boucle sans fin. spec.max_total_transitions vaut 50 par défaut, 100 au plus, après quoi "the workflow terminates" (le workflow se termine). Le max_state_visits de chaque état vaut 5 par défaut, 20 au plus. Chaque état a aussi un timeout, 300s par défaut. spec.context contient des constantes que chaque état lit sous la forme {{workflow.context.KEY}}, comme une limite d'itérations ou un seuil.

Étape 3. Choisir un type pour chaque état

Chaque état nomme un kind. La référence en liste huit :

Agent lance un agent déployé et écrit ses status, output, score et iterations sous le nom de l'état.
System lance une command shell et enregistre stdout, stderr et exit_code.
Action exécute l'une des opérations propres au workflow, comme update_blackboard ou repository_commit : "no agent chooses or calls it, and no shell runs." (aucun agent ne la choisit ni ne l'appelle, et aucun shell ne tourne.)
Human suspend l'exécution jusqu'à ce qu'une personne réponde.
ParallelAgents lance plusieurs juges et combine leurs scores selon une stratégie de consensus.
ContainerRun et ParallelContainerRun lancent des étapes en conteneur, pour le travail de CI et de CD.
Subworkflow démarre un autre workflow, bloquant ou fire-and-forget, jusqu'à une profondeur de 10 au plus.

Étape 4. Écrire les transitions dans l'ordre où elles doivent être essayées

Les transitions sont "evaluated top-to-bottom. The first matching transition is taken." (évaluées de haut en bas. La première transition qui correspond est prise.) Chacune nomme un état target et, au besoin, une condition. Cet état System, tiré de l'exemple de la référence, branche sur le code de sortie :

    EXECUTE:
      kind: System
      command: python main.py
      env:
        CODE: "{{GENERATE.output}}"
        PYTHONPATH: /workspace
      transitions:
        - condition: exit_code_zero
          target: VALIDATE
        - condition: exit_code_non_zero
          target: REFINE
          feedback: "Execution failed: {{EXECUTE.output.stderr}}"

Les conditions de chaque type : on_success et on_failure pour la plupart ; exit_code_zero, exit_code_non_zero et exit_code avec une value pour System et ContainerRun ; input_equals, input_equals_yes et input_equals_no pour Human ; consensus, all_approved et any_rejected pour ParallelAgents ; custom avec une expression Handlebars pour tous ; et always, ou aucune condition, comme repli inconditionnel. Le conseil de la référence : "Always include an unconditional fallback as the last transition." (Mettez toujours un repli inconditionnel en dernière transition.)

Étape 5. Brancher sur un score

    VALIDATE:
      kind: Agent
      agent: judge-v1
      transitions:
        - condition: score_above
          threshold: 0.95
          target: COMPLETE
        - condition: score_below
          threshold: 0.95
          target: REFINE
          feedback: "{{VALIDATE.output.reasoning}}"

Les deux comparaisons sont strictes : un score d'exactement 0.95 ne prend aucune des deux transitions ci-dessus. Le score est lu dans le score de l'état, sinon dans final_score, sinon dans consensus.score. Un état sans score ne correspond à aucune des deux, et si rien d'autre ne correspond, l'exécution échoue avec State "<name>" carries no score for its score transitions. score_between prend des min et max inclusifs pour un état Agent.

Étape 6. Transmettre ce qui s'est passé à l'état suivant

La chaîne feedback d'une transition devient {{state.feedback}} dans l'état visé ; c'est ainsi qu'un message d'échec atteint l'agent qui réessaie. Chaque état terminé est écrit dans le Blackboard sous son nom, et les états suivants lisent {{EXECUTE.output.stdout}} ou {{VALIDATE.score}}. Gardez deux espaces de noms séparés : {{input.KEY}} est ce que l'appelant a passé et "is immutable" (est immuable), tandis que {{blackboard.KEY}} grandit au fil de l'exécution. Un modèle qui nomme une clé qu'aucun état n'a encore écrite affiche un marqueur visible, ERROR: missing key avec le nom de l'état, plutôt qu'une chaîne vide.

Étape 7. Boucler avec une garde, et terminer l'exécution

    REFINE:
      kind: System
      command: update_context
      env:
        ITERATION: "{{blackboard.iteration_number + 1}}"
        ERRORS: "{{state.feedback}}"
      transitions:
        - condition: custom
          expression: "{{blackboard.iteration_number < workflow.context.max_iterations}}"
          target: GENERATE
        - condition: custom
          expression: "{{blackboard.iteration_number >= workflow.context.max_iterations}}"
          target: FAILED

    COMPLETE:
      kind: System
      command: finalize
      transitions: []

Un état avec transitions: [] est final : "When reached, the workflow execution completes with status completed." (Quand il est atteint, l'exécution du workflow se termine avec le statut completed.) Donnez à la boucle sa propre garde sur le Blackboard, comme ci-dessus, en plus de compter sur max_state_visits.

Étape 8. Valider, déployer, lancer et suivre les transitions

aegis workflow validate ./pipeline.yaml
aegis workflow deploy ./pipeline.yaml
aegis workflow run dev-pipeline --input '{"task": "..."}'
aegis workflow logs <execution_id> --transitions

validate vérifie le manifeste en local ; deploy l'enregistre et échoue sur un nom et une version existants sauf si vous ajoutez --force ; logs --transitions montre "state entries/exits only" (seulement les entrées et sorties d'états), le moyen le plus rapide de voir quelle branche chaque état a prise.

Ce que la documentation laisse ouvert

Les mots de la porte. Dans la Workflow Manifest Reference, input_equals_yes accepte "yes", "approve", "approved" ou "true" ; la page Human Approvals dit yes, y ou 1. Testez votre porte avant de vous fier à l'une ou l'autre liste.
Une seconde syntaxe. L'exemple Blackboard de la même page écrit kind: agent, input_template et des transitions en on: success avec next:, là où le reste de la référence écrit kind: Agent, input, condition et target. La page ne dit pas si le moteur accepte les deux.
L'arithmétique dans les modèles. L'exemple pose {{blackboard.iteration_number + 1}}, mais les opérateurs listés pour les expressions sont seulement des comparaisons et de la logique, sans +.
Aucune correspondance. Hors du cas du score, la référence ne dit pas ce qui se passe quand un état se termine et qu'aucune de ses transitions ne correspond.
Combien de types. L'index de la documentation décrit "all seven state kinds" (les sept types d'état) ; le tableau de la référence en liste huit.

Ensuite

Pour l'état Human en détail, avec ce que voit la personne qui relit et ce que signifie le silence, lisez Donner une étape d'approbation à un orchestrateur : un modèle, avec AEGIS comme exemple concret. AEGIS s'installe avec la commande affichée sur 100monkeys.ai :

curl -fsSL https://get.100monkeys.ai | bash

Installer AEGIS depuis 100monkeys.ai