Blog · Guia · 28 de outubro de 2026

O manifesto de agente do AEGIS: cada campo e o que ele impõe

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 Agent Manifest Reference, a CLI Reference, a Workflow Manifest Reference e Human Approvals, e revisado pela empresa; esta versão em português é uma tradução do guia original em inglês. Nomes de campos, valores padrão e mensagens de recusa são citados dessas páginas, em inglês com a tradução ao lado.

O AEGIS by 100monkeys.ai, in beta, executa um agente a partir de um único arquivo YAML. A documentação chama o manifesto de agente de "the source of truth for an Agent's identity, capabilities, security constraints, and execution requirements." (a fonte da verdade sobre a identidade, as capacidades, as restrições de segurança e os requisitos de execução de um agente). Este guia percorre o manifesto seção por seção e diz, para cada campo, o que o orquestrador faz com ele.

Passo 1. Escreva o cabeçalho

apiVersion: 100monkeys.ai/v1
kind: Agent
metadata:
  name: pr-reviewer
  version: "1.0.0"
  description: "Reviews pull request diffs and returns structured feedback."

apiVersion e kind precisam ter exatamente esses valores. name precisa casar com ^[a-z0-9][a-z0-9-]{0,62}$, e o par de name e version precisa ser único: implantar o mesmo par de novo falha, a menos que você passe --force. labels e annotations são mapas opcionais de chave e valor para descoberta e anotações.

Passo 2. Escolha um runtime

spec.runtime é a única parte obrigatória de spec. Informe language e version (python, javascript, typescript, rust ou go, resolvidos para uma imagem oficial) ou uma image totalmente qualificada, nunca os dois; language sem version é inválido. image_pull_policy tem padrão IfNotPresent. model indica um alias de modelo do aegis-config.yaml, e um alias que gera imagens é recusado. isolation aceita inherit, docker, firecracker e process; a referência marca docker como Fase 1 e os outros dois como Fase 2.

Passo 3. Dê uma tarefa

task.instruction é a orientação com que o agente trabalha, e defini-la "auto-enables semantic validation" (ativa automaticamente a validação semântica). task.prompt_template é um template Handlebars; suas variáveis são {{intent}}, {{instruction}}, {{input}}, {{iteration_number}}, {{previous_error}} e {{context}}. spec.input_schema, um JSON Schema com type: object, declara entradas nomeadas e as valida antes de o agente rodar.

Passo 4. Declare só o acesso de que ele precisa

"All permissions are deny-by-default." (Todas as permissões são negadas por padrão.) Sem spec.security, o agente não tem rede nem acesso ao sistema de arquivos. network.mode é allow (só a allowlist), deny (tudo menos a denylist) ou none, que "attaches no network interface to the container" (não conecta nenhuma interface de rede ao contêiner). filesystem.read e filesystem.write listam caminhos, com globs permitidos. Os recursos têm padrão cpu: 1000 milicores, memory: "512Mi", disk: "1Gi" e timeout: "1800s", com máximo de uma hora. Quando o agente pode tentar duas vezes ou mais, o timeout precisa comportar duas tentativas inteiras, 2 × (iteration_timeout + o timeout_seconds dos juízes) + 45 s, ou o agente "is refused on create and update" (é recusado na criação e na atualização).

Passo 5. Monte os volumes

Cada entrada de spec.volumes[] tem um name, uma storage_class (ephemeral exige ttl_hours; persistent exige source.volume_id), um mount_path com raiz em /workspace e um access_mode. O acesso de leitura e escrita a um volume persistente é exclusivo de uma execução por vez. Um volume que não pode ser montado interrompe a iteração: o agente "never runs without its volume." (nunca roda sem seu volume).

Passo 6. Defina como ele itera e o que conta como pronto

execution.mode é iterative (o padrão) ou one-shot. max_iterations vai de 1 a 20, padrão 5, e max_retries é o mesmo campo. iteration_timeout tem padrão 600s e llm_timeout_seconds 300. Depois de cada tentativa, validation roda em ordem: exit_code, json_schema, regex, semantic (um agente juiz, min_score padrão 0.7) ou multi_judge. Uma falha volta para o agente como {{previous_error}}. tool_validation julga cada chamada de ferramenta antes de ela rodar; ali só entradas semantic são usadas. outputs nomeia os arquivos que a execução precisa deixar, cada um com min_bytes e magic opcionais, e a falta de um deles faz a tentativa falhar.

Passo 7. Conceda ferramentas

spec.tools aceita strings como "mcp:filesystem" ou objetos com name, server e config. Para rodar comandos, declare executor: "builtin:cmd" com uma subcommand_allowlist obrigatória, um mapa de comando para primeiros argumentos permitidos; qualquer outra chamada "is rejected with a policy violation" (é rejeitada com uma violação de política). O orquestrador verifica se as declarações dão conta do trabalho: um agente que precisa gravar arquivos mas não declara ferramentas, ou que declara fs.write sem um volume de leitura e escrita, é recusado no deploy com uma frase que diz o motivo.

Passo 8. Passe configuração e segredos

Os valores de spec.env são um literal, "secret:<name>" (injetado a partir do OpenBao e "never logged", nunca registrado) ou "config:<key>". spec.security_context é só para operadores da plataforma; uma conta de consumidor que o define recebe 403 Forbidden.

Passo 9. Valide e depois implante

aegis agent deploy ./agent.yaml --validate-only
aegis agent deploy ./agent.yaml

--validate-only analisa e valida sem implantar. aegis agent show <AGENT_ID> mostra de volta o manifesto armazenado.

Onde fica um sim humano

O manifesto de agente não tem campo de aprovação. O sim de uma pessoa pertence a um workflow, num estado de kind: Human: prompt é obrigatório, timeout tem padrão 3600s e default_response é a resposta usada quando o prazo acaba; sem ela, o workflow falha. Human Approvals diz que a transição input_equals_yes de um portão aceita yes e input_equals_no aceita no, e que uma resposta que nenhuma transição aceita é recusada e pedida de novo.

O que a documentação deixa em aberto

As duas referências discordam sobre as palavras do portão: a Workflow Manifest Reference faz input_equals_yes aceitar "yes", "approve", "approved" ou "true"; Human Approvals diz yes, y ou 1. Este guia segue Human Approvals.
metadata.version é chamado de "semantic version" (versão semântica) no exemplo e de "Manifest schema version" (versão do esquema do manifesto) na tabela.
firecracker e process aparecem como valores válidos de isolation, marcados como Fase 2; a referência não diz o que acontece hoje quando um manifesto indica um deles.

Para rodar um manifesto do início ao fim num servidor novo, leia Instale o AEGIS numa VPS Ubuntu nova e rode sua primeira tarefa aprovada. O AEGIS é instalado com o comando que aparece em 100monkeys.ai:

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

Instale o AEGIS pelo 100monkeys.ai