Blog · Guia · 28 de outubro de 2026

Como dar a um orquestrador uma etapa de aprovação: um padrão, com o AEGIS como exemplo prático

Também em: English, Español, 日本語, Deutsch, Français · Todos os guias em português

Aviso: a 100monkeys.ai desenvolve o AEGIS, o exemplo prático deste guia, então leia as partes sobre o AEGIS como o relato de quem o fabrica. O padrão em si é geral e vale para qualquer orquestrador. Este guia foi redigido por um dos nossos agentes de IA a partir da documentação pública do AEGIS e revisado pela empresa; esta versão em português é uma tradução do guia original em inglês.

Uma etapa de aprovação é um ponto de uma execução automatizada em que o trabalho para, uma pessoa lê exatamente o que está prestes a acontecer e a execução só continua com a resposta dela. Quase todo orquestrador consegue pausar. Poucos fazem a pausa se sustentar. Este é o padrão que usamos, passo a passo, com o AEGIS by 100monkeys.ai, in beta, como exemplo prático.

O padrão em um parágrafo

Coloque o portão depois que o agente preparou o ato e antes que o ato aconteça. Mostre ao revisor a própria coisa preparada, não um resumo dela. Decida de antemão o que o silêncio significa. Encaminhe as duas respostas de forma explícita. Deixe o revisor responder de onde ele já está e guarde a resposta no histórico da execução. Limite as novas tentativas para que um rascunho rejeitado não fique em loop para sempre.

Passo 1. Liste os atos que precisam de uma pessoa

Nem toda etapa precisa de um portão; um portão em tudo ensina as pessoas a aprovar sem ler. Coloque portão nos atos que saem do sandbox e não podem ser desfeitos: enviar uma mensagem para alguém de fora, fazer merge em um branch protegido, gastar dinheiro, apagar dados, publicar. Todo o resto pode rodar sob uma política escrita antes. Nosso artigo Red levers (em inglês) chama isso de os dois tipos de parada: limites definidos antes da execução, impostos pelo runtime, e uma aprovação no ato, vinculada a um único ato.

Passo 2. Divida o trabalho do agente no ato

Um agente que redige e envia em uma única etapa não pode ser barrado no meio. Divida-o em um estado que prepara e um estado que age, para que o portão tenha onde ficar. No AEGIS um workflow é uma máquina de estados declarativa, e o portão é um estado próprio, kind: Human:

spec:
  initial_state: DRAFT
  states:
    DRAFT:
      kind: Agent
      agent: draft-agent
      transitions:
        - condition: on_success
          target: APPROVE
    APPROVE:
      kind: Human
      prompt: |
        About to send:
        {{DRAFT.output}}

        Approve? (yes/no)
      timeout: 86400s
      transitions:
        - condition: input_equals_yes
          target: SEND
        - condition: input_equals_no
          target: DISCARD

A forma segue a página Building Workflows da documentação do AEGIS; draft-agent, SEND e DISCARD representam o seu próprio agente e os seus estados.

Passo 3. Coloque diante do revisor a coisa exata

O prompt do portão é tudo o que o revisor vê, então renderize nele a saída preparada. Os prompts do AEGIS aceitam templates do Blackboard: {{DRAFT.output}} acima é a saída do estado anterior, e a documentação também mostra notas de estados anteriores, como {{QUALITY_CHECK.output.score}}. Um revisor que vê "o agente quer enviar um e-mail" está aprovando uma descrição; um revisor que vê o e-mail está aprovando o e-mail.

Passo 4. Decida o que o silêncio significa

Todo portão precisa de um timeout e de uma regra para quando ele vence. Na página Human Approvals, timeout_seconds tem padrão 3600. Com reject_on_timeout: false, o padrão, um portão sem resposta faz a execução falhar com human_input_timeout. Com reject_on_timeout: true, o silêncio conta como um não e a execução segue a rota de rejeição. Escolha a segunda opção quando uma resposta ausente deve ser um não limpo, e não um erro. Nunca faça do silêncio um sim.

Uma observação sobre os campos: a página Human Approvals usa timeout_seconds e as condições approved e rejected; a página Building Workflows usa timeout e input_equals_yes e input_equals_no. Use uma forma só, de modo consistente, e confira a Workflow Manifest Reference da versão que você roda.

Passo 5. Encaminhe as duas respostas e limite o loop

Um não é uma resposta, não uma falha para tratar depois. Dê a ele um estado de destino: descartar, ou devolver o rascunho ao agente com o comentário do revisor. Se você devolve uma rejeição ao estado de redação, a execução agora tem um loop. O AEGIS o limita: max_state_visits por estado (padrão 5, teto 20) e max_total_transitions por execução (padrão 50, teto 100). Ajuste-os ao número de tentativas que o revisor vai tolerar.

Passo 6. Deixe o revisor responder de onde estiver

Um portão que ninguém vê é um timeout. No AEGIS o mesmo portão pode ser respondido de três formas:

• Pela linha de comando: aegis workflow signal <execution-id> --response yes.
• Pelo seu próprio cliente: liste os portões em espera com GET /v1/workflow-gates?status=pending e responda a um com POST /v1/workflows/executions/{id}/signal, com um corpo como { "response": "yes", "feedback": "Keep the flag name short." }.
• No Zaru Web: um portão de uma execução que você iniciou aparece entre as suas aprovações pendentes, com um botão para cada palavra permitida. A documentação acrescenta que o companheiro do Zaru não recebe nenhuma ferramenta que responda a um portão, em nenhum modo, então o modelo que preparou o ato não pode aprová-lo.

Essa última propriedade é a que vale procurar em qualquer orquestrador: o agente não pode ter a chave do próprio portão.

Passo 7. Guarde a resposta

Uma aprovação é uma evidência. Depois que um portão é respondido ou vence, o AEGIS continua listando-o: ?status=answered devolve cada portão com a palavra escolhida, o comentário, quando ele fechou e o que a execução fez então. Registre também quem respondeu; o endpoint de aprovação na página Human Approvals aceita um campo approved_by, e uma rejeição exige um reason.

Passo 8. Teste o portão antes de confiar nele

Rode o workflow três vezes: responda sim, responda não e deixe vencer. Confirme que cada rota chega aonde você queria e que nada depois do portão rodou antes da resposta. Depois altere o rascunho com o portão já publicado e confirme que o revisor vê o que de fato vai rodar. Se o seu orquestrador vincula a aprovação a uma descrição em vez do conteúdo, é aqui que você descobre.

Para onde ir agora

Para testar o padrão de ponta a ponta em um servidor seu, siga Instale o AEGIS numa VPS Ubuntu nova e rode sua primeira tarefa aprovada. Para saber o que registrar e assinar em torno de cada portão, leia Checklist de rastreabilidade para agentes de IA. Para a mesma ideia de aprovação em um assistente pessoal, veja Configure um assistente Zaru que cuida do seu e-mail e da sua agenda com aprovações.

Instale o AEGIS a partir de 100monkeys.ai