Blog · Guia · 28 de outubro de 2026

Como ler o log de uma execução do AEGIS: o que uma chamada de ferramenta selada registra

Também em: English, Español, 日本語 · 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 Deploying & Running Agents, a CLI Reference, a página SEAL Protocol e a página Observability do gateway, e revisado pela empresa; esta versão em português é uma tradução do guia original em inglês. As linhas de log, campos e códigos são os exemplos da própria documentação, não uma saída que capturamos para este guia; as citações ficam em inglês com a tradução ao lado.

AEGIS by 100monkeys.ai, in beta, roda cada agente no seu próprio runtime isolado e envia as chamadas de ferramenta por um protocolo assinado chamado SEAL. Este guia lê uma execução de fora para dentro: o registro da execução, o log de iterações e depois o que a camada SEAL registra sobre uma única chamada de ferramenta, permitida ou recusada.

Por que a execução é a unidade

A página Executions diz sem rodeios: "Each execution is the unit of observability and replay in AEGIS. Logs, tool calls, blackboard snapshots, and refinement trajectories are all anchored to an execution ID." (Cada execução é a unidade de observabilidade e de replay no AEGIS. Logs, chamadas de ferramenta, snapshots do blackboard e trajetórias de refinamento ficam todos ancorados a um ID de execução.) Cada passo abaixo parte desse id. Uma execução percorre o loop "Execute, Evaluate, Refine" (executar, avaliar, refinar) e termina "when the agent produces output that satisfies its evaluation criteria, when the iteration budget is exhausted, or when an unrecoverable failure occurs" (quando o agente produz uma saída que atende aos critérios de avaliação, quando o orçamento de iterações se esgota ou quando ocorre uma falha irrecuperável).

Passo 1. Encontre o id da execução

aegis task execute imprime o id ao começar (Execution started: <id>). Para execuções que você não iniciou, liste-as:

aegis task list
aegis task list --agent-id <AGENT_ID>
aegis task list --limit 20

Uma execução agendada traz o id na lista de execuções do agendamento; uma execução de workflow aparece em aegis workflow executions list.

Passo 2. Leia o registro da execução

aegis task status <EXECUTION_ID> --output json

A documentação diz que isso "returns the execution record, including status, start/end timestamps, total iterations, and each iteration's status and validation scores" (retorna o registro da execução, com o status, os horários de início e fim, o total de iterações e o status e as notas de validação de cada iteração). Leia primeiro o número de iterações. Uma iteração aprovada é uma execução limpa; várias iterações significam que a saída falhou na validação e foi refinada, e o log mostrará o motivo.

Passo 3. Leia o log de iterações

aegis task logs <EXECUTION_ID>

O exemplo da documentação do que uma execução imprime, linha por linha:

[2026-02-23T10:00:01Z] Execution a1b2c3d4-1111-... Started
[2026-02-23T10:00:01Z] Iteration 1 Started
[2026-02-23T10:00:03Z] Tool: fs.write /workspace/solution.py (234 bytes)
[2026-02-23T10:00:04Z] Tool: cmd.run python /workspace/solution.py
[2026-02-23T10:00:05Z] Tool: fs.write /workspace/result.json (89 bytes)
[2026-02-23T10:00:06Z] Iteration 1 Completed
[2026-02-23T10:00:06Z] Validation: exit_code=PASS json_schema=PASS (score=1.0)
[2026-02-23T10:00:06Z] Execution a1b2c3d4-1111-... Completed (1 iteration, 5.2s)

Leia como três tipos de linha: o ciclo de vida (início, fim), uma linha Tool: por chamada que o agente fez e uma linha Validation: com o veredito de cada validador e a nota. Acrescente --errors-only para ver só as falhas, --verbose para mais detalhes e --follow para acompanhar uma execução ao vivo. Para um workflow, aegis workflow logs <EXECUTION_ID> --transitions mostra só as mudanças de estado.

Passo 4. O que está por trás de cada linha Tool

Cada linha Tool: é uma chamada que passou pelo SEAL. "Every tool call is wrapped in a SealEnvelope" (toda chamada de ferramenta é embrulhada num SealEnvelope): o protocolo (seal/v1), um security_token (um JWT emitido na atestação), uma signature Ed25519, o payload (para chamadas no estilo MCP, um tools/call JSON-RPC), um container_id e um timestamp inteiro.

As claims do token são o que liga a chamada à sua execução: sub (quem chama), scp (o nome do contexto de segurança), wid (a carga de trabalho) e exec_id, que "ties every call in a session to one audit chain" (liga cada chamada de uma sessão a uma única cadeia de auditoria). Então o id de execução do passo 1 é a chave que une a linha do log ao seu envelope.

Passo 5. Leia por que uma chamada foi permitida

O gateway faz nove verificações antes de encaminhar uma chamada: o campo de protocolo, a assinatura e a validade do token, a chave registrada de quem chama, a assinatura do envelope sobre uma mensagem canônica, um timestamp dentro de 30 segundos e, por fim, o contexto de segurança nomeado em scp. Essa última verificação nega tudo o que está na lista de negação, permite uma chamada só quando uma capacidade corresponde à ferramenta, caminho, domínio ou subcomando e ao limite de taxa, e caso contrário nega "(default deny)" (negação por padrão). O contexto não pode mudar no meio da sessão: "callers cannot widen their context, switch contexts, or impersonate a different one" (quem chama não pode ampliar o contexto, trocar de contexto nem se passar por outro).

Passo 6. Leia uma recusa

Uma chamada recusada não é um buraco silencioso no log. No SEAL Gateway ela responde com um código numérico. Os que você mais vai encontrar:

• 2000 a 2006: política. Ferramenta não concedida, ferramenta na lista de negação, caminho fora de path_allowlist, comando fora de command_allowlist, domínio fora de domain_allowlist, limite de taxa atingido, nenhuma capacidade correspondeu.
• 1003 TOKEN_EXPIRED: o token expirou, o timestamp ficou fora da janela de 30 segundos ou o jti já tinha sido visto, que é como um envelope reenviado aparece.
• 1001 e 1002: uma assinatura malformada ou que não se verifica.

A documentação diz "switch on error.code, not on the status" (decida pelo error.code, não pelo status) e aponta uma armadilha: o próprio POST /v1/seal/invoke do orquestrador responde a uma recusa com um código em texto, como TOOL_NOT_ALLOWED, em vez de um número.

Passo 7. Leia o registro de auditoria

A página SEAL Protocol lista os eventos que cada chamada produz, entre eles ToolCallAuthorized e PolicyViolationBlocked, e o que cada um captura: a assinatura, o timestamp e o jti do envelope; os sub, scp, wid e exec_id do token; o nome da ferramenta e o "payload digest (not the full payload, payloads are not logged by default)" (resumo do payload, não o payload completo; payloads não são registrados por padrão); e "the policy decision (ALLOW or DENY plus the deciding rule, if any)" (a decisão de política, ALLOW ou DENY, mais a regra que decidiu, se houver). A assinatura é o que dá o não repúdio: "only the holder of the ephemeral private key could have produced a valid signature" (só quem detém a chave privada efêmera poderia ter produzido uma assinatura válida).

Num SEAL Gateway independente essas linhas ficam na tabela gateway_events. Ainda não há endpoint REST para elas; a documentação dá SQL no lugar:

SELECT event_type, created_at, payload
  FROM gateway_events
  WHERE payload->>'execution_id' = 'exec-1234'   -- Postgres JSONB syntax
  ORDER BY created_at;

A tabela só aceita inserções, então envie-a ao seu SIEM consultando os ids acima do último que você enviou.

O que a documentação deixa em aberto

• As duas listas de eventos diferem. A página SEAL Protocol nomeia PolicyViolationBlocked; a tabela gateway_events do gateway, como Observability a lista, não. Não se diz qual tabela guarda uma negação.
• Portas. A página do SEAL coloca o orquestrador na 8080; a porta de API padrão da CLI é 8088.
• O gateway ainda não tem endpoint de métricas nem traces OTLP; a própria página Observability diz isso.

Próximos passos

Para saber o que quem revisa precisa além desses logs, leia Checklist de rastreabilidade para agentes de IA.

Instale o AEGIS pelo 100monkeys.ai