Blog · Guia · 29 de outubro de 2026

Estados e transições de um workflow do AEGIS, passo a passo

Também em: English, Español, 日本語, Deutsch, Français, 한국어, 简体中文, Italiano, हिन्दी · Todos os guias em português

Aviso: a 100monkeys.ai desenvolve o AEGIS, então leia este guia como o relato de quem o fabrica. Ele foi redigido por um dos nossos agentes de IA a partir da documentação pública do AEGIS, principalmente a Workflow Manifest Reference e a CLI Reference, e revisado pela empresa; esta versão em português é uma tradução do guia original em inglês. Cada linha de YAML e cada comando abaixo foram copiados dessas páginas, e nenhum foi executado para este guia. As citações ficam em inglês com a tradução ao lado. Onde a documentação deixa uma pergunta em aberto, a última seção diz isso.

AEGIS by 100monkeys.ai, in beta, executa um workflow como uma máquina de estados finitos escrita num único arquivo YAML. A referência o chama de "a durable, restartable sequence" (uma sequência durável e reiniciável) que coordena agentes, contêineres, comandos do sistema e portões de aprovação humana. Este guia escreve um estado de cada vez e mostra como o motor escolhe o próximo.

Passo 1. Escreva o cabeçalho

apiVersion: 100monkeys.ai/v1
kind: Workflow

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

apiVersion deve ser exatamente 100monkeys.ai/v1 e kind exatamente Workflow. name segue ^[a-z0-9][a-z0-9-]{0,62}$, e o par de nome e versão deve ser único: sobrescrever uma versão existente exige o parâmetro force. metadata.input_schema é opcional; quando presente, a entrada de quem chama é validada antes de a execução começar, e uma carga que falha é "rejected with HTTP 422; no workflow execution is created." (rejeitada com HTTP 422; nenhuma execução do workflow é criada).

Passo 2. Nomeie o primeiro estado e os limites

Em spec, initial_state é obrigatório e deve existir em spec.states. Dois limites interrompem um laço que nunca acaba. spec.max_total_transitions vale 50 por padrão, com teto de 100, depois do qual "the workflow terminates" (o workflow termina). O max_state_visits de cada estado vale 5 por padrão, com teto de 20. Cada estado tem ainda um timeout, 300s por padrão. spec.context guarda constantes que todo estado lê como {{workflow.context.KEY}}, como um limite de iterações ou um limiar.

Passo 3. Escolha um tipo para cada estado

Todo estado nomeia um kind. A referência lista oito:

Agent executa um agente implantado e grava seu status, output, score e iterations sob o nome do estado.
System executa um command de shell e registra stdout, stderr e exit_code.
Action executa uma das operações do próprio workflow, como update_blackboard ou repository_commit: "no agent chooses or calls it, and no shell runs." (nenhum agente a escolhe nem a chama, e nenhum shell é executado).
Human suspende a execução até que uma pessoa responda.
ParallelAgents executa vários juízes e combina suas pontuações por uma estratégia de consenso.
ContainerRun e ParallelContainerRun executam etapas em contêineres, para trabalho de CI e CD.
Subworkflow inicia outro workflow, bloqueante ou sem esperar resposta, até uma profundidade de no máximo 10.

Passo 4. Escreva as transições na ordem em que quer que sejam testadas

As transições são "evaluated top-to-bottom. The first matching transition is taken." (avaliadas de cima para baixo. A primeira transição que corresponde é tomada). Cada uma nomeia um estado target e, opcionalmente, uma condition. Este estado System, do próprio exemplo da referência, ramifica pelo código de saída:

    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}}"

As condições que cada tipo pode usar: on_success e on_failure para a maioria; exit_code_zero, exit_code_non_zero e exit_code com um value para System e ContainerRun; input_equals, input_equals_yes e input_equals_no para Human; consensus, all_approved e any_rejected para ParallelAgents; custom com uma expression Handlebars para qualquer tipo; e always, ou nenhuma condição, como alternativa incondicional. O conselho da referência: "Always include an unconditional fallback as the last transition." (Inclua sempre uma alternativa incondicional como última transição).

Passo 5. Ramifique por uma pontuação

    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}}"

As duas comparações são estritas, então uma pontuação de exatamente 0.95 não toma nenhuma das duas transições acima. A pontuação é lida do score do estado, senão de final_score, senão de consensus.score. Um estado sem pontuação não corresponde a nenhuma, e se nada mais corresponder a execução falha com State "<name>" carries no score for its score transitions. score_between recebe min e max inclusivos para um estado Agent.

Passo 6. Leve o que aconteceu ao próximo estado

A string feedback de uma transição vira {{state.feedback}} no estado a que ela leva; é assim que uma mensagem de falha chega ao agente que tenta de novo. Cada estado concluído é gravado no Blackboard sob seu nome, de modo que estados posteriores leem {{EXECUTE.output.stdout}} ou {{VALIDATE.score}}. Mantenha dois espaços de nomes separados: {{input.KEY}} é o que quem chama passou e "is immutable" (é imutável), enquanto {{blackboard.KEY}} cresce conforme a execução avança. Um template que nomeia uma chave que nenhum estado gravou ainda mostra um marcador visível, ERROR: missing key com o nome do estado, em vez de uma string vazia.

Passo 7. Faça um laço com guarda e encerre a execução

    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: []

Um estado com transitions: [] é final: "When reached, the workflow execution completes with status completed." (Ao ser alcançado, a execução do workflow termina com status completed). Dê ao laço sua própria guarda no Blackboard, como acima, além de contar com max_state_visits.

Passo 8. Valide, implante, execute e acompanhe as transições

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

validate verifica o manifesto localmente; deploy o registra e falha com um nome e versão existentes, a menos que você acrescente --force; logs --transitions mostra "state entries/exits only" (apenas entradas e saídas de estados), o jeito mais rápido de ver que ramo cada estado tomou.

O que a documentação deixa em aberto

Palavras do portão. A Workflow Manifest Reference faz input_equals_yes aceitar "yes", "approve", "approved" ou "true"; a página Human Approvals diz yes, y ou 1. Teste seu portão antes de confiar em qualquer das duas listas.
Uma segunda sintaxe. O exemplo de Blackboard na mesma página escreve kind: agent, input_template e transições como on: success com next:, enquanto o resto da referência escreve kind: Agent, input, condition e target. A página não diz se o motor aceita as duas.
Aritmética em templates. O exemplo define {{blackboard.iteration_number + 1}}, mas os operadores listados para expressões são só de comparação e lógica, sem +.
Nenhuma correspondência. Fora o caso da pontuação, a referência não diz o que acontece quando um estado termina e nenhuma de suas transições corresponde.
Quantos tipos. O índice da documentação fala em "all seven state kinds" (os sete tipos de estado); a tabela da referência lista oito.

Para o estado Human em detalhe, com o que o revisor vê e o que o silêncio significa, leia Como dar a um orquestrador uma etapa de aprovação. O AEGIS se instala com o comando mostrado em 100monkeys.ai:

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

Instale o AEGIS pelo 100monkeys.ai