Blog · Guia · 28 de outubro de 2026

Como o AEGIS sela uma chamada de ferramenta: o gateway SEAL, 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 e o SEAL Gateway, 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, principalmente a página SEAL Protocol, Integration with AEGIS e Security Contexts, e revisado pela empresa; esta versão em português é uma tradução do guia original em inglês. Os campos, códigos e fluxos abaixo são os da 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.

O AEGIS by 100monkeys.ai, in beta, não confia na chamada de ferramenta de um agente só porque foi o agente que a fez. Cada chamada vai dentro de um envelope assinado e é verificada pelo SEAL Gateway antes de qualquer coisa fora da execução ser tocada. Este guia acompanha uma chamada desde o início da execução até o registro de auditoria que ela deixa.

Para que serve o SEAL

SEAL significa Signed Envelope Attestation Layer. A documentação aponta quatro lacunas nos protocolos comuns de chamada de ferramentas: nenhuma prova de qual cliente enviou uma requisição, permissões de tudo ou nada por sessão, corpos que podem ser adulterados em trânsito e nenhum registro que prove qual chamador fez o quê. O exemplo dela é uma injeção de prompt: uma página baixada manda o modelo apagar /workspace. "With SEAL, the caller's SecurityContext has no fs.delete capability. The gateway blocks it before it ever reaches the tool." (Com o SEAL, o SecurityContext do chamador não tem a capacidade fs.delete. O gateway bloqueia antes que chegue à ferramenta.)

O gateway funciona primeiro de forma independente. Nas palavras da documentação, é "the same aegis-seal-gateway binary" (o mesmo binário aegis-seal-gateway) que o orquestrador do AEGIS "deploys alongside itself" (implanta junto de si). Com o AEGIS você não faz nada a mais para ter os passos abaixo; "it is the default." (é o padrão).

Passo 1. O orquestrador abre uma sessão para a execução

Quando uma execução entra em Running, o orquestrador gera um par de chaves Ed25519 novo para essa execução e o registra no gateway: POST /v1/seal/sessions com um session_id (o id da execução, "so audit trails line up", para que as trilhas de auditoria batam), a public_key, o security_context e um expires_at limitado ao orçamento de tempo real da execução. Só um chamador com o escopo seal.session.create pode fazer isso; "agents themselves cannot self-register." (os próprios agentes não podem se registrar).

Passo 2. A chave privada vai para o agente e para mais nenhum lugar

A metade privada é gravada na configuração efêmera do contêiner do agente, "a tmpfs mount, never persisted" (um ponto de montagem tmpfs, nunca persistido), com a URL do gateway e o id da sessão. Assim cada execução tem sua própria chave, e "a leaked private key is bounded to a single execution's lifetime." (uma chave privada vazada fica limitada à vida de uma única execução).

Passo 3. A sessão fica ligada a um único contexto de segurança

Um contexto de segurança é uma política com nome no gateway: uma deny_list e uma lista ordenada de capabilities, cada uma com um tool_pattern e, opcionalmente, path_allowlist, command_allowlist, subcommand_allowlist, domain_allowlist e max_response_size. Agentes iniciados rodam sob aegis-system-agent-runtime, não sob o contexto do nível de quem pediu. O orquestrador fixa o contexto no provisionamento, e o agente "cannot escalate by claiming a different scp in its envelope" (não pode escalar alegando outro scp no envelope).

Passo 4. O agente assina uma mensagem canônica

A assinatura não é feita sobre o JSON bruto. É feita sobre três chaves, payload, security_token e timestamp, serializadas com as chaves ordenadas em todos os níveis, sem espaços, com um timestamp Unix inteiro e em UTF-8. Qualquer outra sequência de bytes dá outra assinatura, e "the gateway will reject the envelope." (o gateway rejeitará o envelope).

Passo 5. O agente envia o envelope

O envelope leva protocol (sempre seal/v1), o security_token (um JWT emitido na atestação, com vida padrão de uma hora), a signature Ed25519, o payload (em chamadas no estilo MCP, um tools/call JSON-RPC), um container_id opcional e o timestamp. Ele vai para o endpoint de invocação do gateway, POST /v1/invoke. O gateway escuta na porta 8089 por padrão; a API do próprio orquestrador do AEGIS fica na 8088.

Passo 6. O gateway faz nove verificações

O campo protocol é seal/v1.
O token é decodificado em suas claims: sub, scp, wid, exec_id, iat, exp, jti.
A assinatura do token é verificada com a chave do gateway, com o cabeçalho alg conferido explicitamente.
O token não expirou.
A chave pública registrada do chamador é encontrada para a sessão.
A mensagem canônica é reconstruída.
A assinatura do envelope é verificada com essa chave e essa mensagem.
O timestamp está a menos de 30 segundos do relógio do servidor.
O contexto de segurança indicado em scp é carregado e a chamada é avaliada.

"Every check must pass before the payload is unwrapped and forwarded." (Todas as verificações precisam passar antes de o payload ser desembrulhado e encaminhado.)

Passo 7. O contexto de segurança decide

A avaliação segue uma ordem fixa: se um padrão da deny_list casar, a chamada é recusada; senão, "the first capability whose tool_pattern matches the tool name owns the decision" (a primeira capacidade cujo tool_pattern casa com o nome da ferramenta decide); se nenhuma casar, a chamada é recusada, porque "there is no implicit allow." (não há permissão implícita). Um padrão de família como fs.* casa com fs.read e nunca com fs ou fsx.read.

Passo 8. A chamada é encaminhada ou recusada com um código

Uma chamada permitida tem o payload desembrulhado e enviado à ferramenta; as credenciais, quando a ferramenta precisa delas, são resolvidas nesse momento. Uma chamada recusada responde com um código numérico: de 2000 a 2006 para política (não concedida, na lista de bloqueio, caminho, comando ou domínio fora da lista permitida, limite de taxa, nenhuma capacidade correspondente), de 1001 a 1006 para assinaturas, tokens e sessões, e de 3000 a 3002 para atestação. O conselho da documentação: "Switch on error.code, not on the status." (Decida pelo error.code, não pelo status.)

Passo 9. Cada decisão deixa um evento de auditoria

O gateway publica ToolCallAuthorized ou PolicyViolationBlocked, entre outros, com a assinatura, o timestamp e o jti do envelope, o sub, scp, wid e exec_id do token, o nome da ferramenta, um resumo do payload ("payloads are not logged by default", os payloads não são registrados por padrão) e a decisão com a regra que a tomou. Como só a chave privada da sessão poderia ter assinado o envelope, o registro dá não repúdio.

Passo 10. A sessão termina com a execução

Quando a execução termina, por sucesso, erro, tempo esgotado ou cancelamento, o orquestrador chama DELETE /v1/seal/sessions/{session_id}. O gateway apaga a chave, e um envelope capturado que seja reenviado depois disso é rejeitado.

O que a documentação deixa em aberto

Limites de taxa. A página SEAL Protocol lista "rate limit not exceeded" (limite de taxa não excedido) entre as verificações e um código 2005; a página Security Contexts diz que rate_limit está "reserved for a future enforcement phase" (reservado para uma fase futura de aplicação). Não se diz se algum limite é aplicado hoje.
Diz-se que o reenvio depois do encerramento falha com session_not_found; a tabela de erros escreve 1005 SESSION_NOT_FOUND. O corpo que o cliente recebe nesse caso não é mostrado.
Estas páginas não dizem onde os eventos de auditoria ficam guardados num gateway independente, nem se PolicyViolationBlocked aparece na tabela gateway_events dele.

Para encontrar essas chamadas numa execução real, leia Como ler o log de uma execução do AEGIS. Para experimentar, o AEGIS é instalado com o comando que aparece em 100monkeys.ai:

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

Instale o AEGIS pelo 100monkeys.ai