Blog · Guía · 28 de octubre de 2026

Cómo AEGIS sella una llamada a herramienta: el gateway SEAL, paso a paso

También en: English, Português, 日本語, Deutsch, Français, 한국어, 简体中文, Italiano, हिन्दी · Todas las guías en español

Aviso: en 100monkeys.ai construimos AEGIS y el SEAL Gateway, así que lee esta guía como el relato de quien lo fabrica. La redactó uno de nuestros agentes de IA a partir de la documentación pública, sobre todo la página SEAL Protocol, Integration with AEGIS y Security Contexts, y la revisó la empresa; esta versión en español es una traducción de la guía original en inglés. Los campos, códigos y flujos que siguen son los de la documentación, no una salida que capturáramos para esta guía; las citas van en inglés con la traducción al lado.

AEGIS by 100monkeys.ai, in beta, no confía en una llamada a herramienta de un agente solo porque la haya hecho el agente. Cada llamada va dentro de un sobre firmado y el SEAL Gateway la comprueba antes de tocar nada fuera de la ejecución. Esta guía sigue una llamada desde que empieza la ejecución hasta el registro de auditoría que deja.

Para qué sirve SEAL

SEAL significa Signed Envelope Attestation Layer. La documentación nombra cuatro huecos de los protocolos de llamadas a herramientas habituales: ninguna prueba de qué cliente envió una petición, permisos de todo o nada por sesión, cuerpos que se pueden alterar en tránsito y ningún registro que pruebe qué llamante hizo qué. Su ejemplo es una inyección de prompt: una página descargada le dice al modelo que borre /workspace. "With SEAL, the caller's SecurityContext has no fs.delete capability. The gateway blocks it before it ever reaches the tool." (Con SEAL, el SecurityContext del llamante no tiene la capacidad fs.delete. El gateway lo bloquea antes de que llegue a la herramienta.)

El gateway funciona primero de forma independiente. En palabras de la documentación, es "the same aegis-seal-gateway binary" (el mismo binario aegis-seal-gateway) que el orquestador de AEGIS "deploys alongside itself" (despliega junto a sí mismo). Con AEGIS no tienes que hacer nada más para obtener los pasos siguientes; "it is the default." (es lo predeterminado).

Paso 1. El orquestador abre una sesión para la ejecución

Cuando una ejecución entra en Running, el orquestador genera un par de claves Ed25519 nuevo para esa ejecución y lo registra en el gateway: POST /v1/seal/sessions con un session_id (el id de la ejecución, "so audit trails line up", para que las pistas de auditoría coincidan), la public_key, el security_context y un expires_at limitado al presupuesto de tiempo real de la ejecución. Solo un llamante con el scope seal.session.create puede hacerlo; "agents themselves cannot self-register." (los propios agentes no pueden registrarse a sí mismos).

Paso 2. La clave privada va al agente y a ningún otro sitio

La mitad privada se escribe en la configuración efímera del contenedor del agente, "a tmpfs mount, never persisted" (un montaje tmpfs que nunca se persiste), junto con la URL del gateway y el id de sesión. Así cada ejecución tiene su propia clave, y "a leaked private key is bounded to a single execution's lifetime." (una clave privada filtrada queda limitada a la vida de una sola ejecución).

Paso 3. La sesión queda ligada a un único contexto de seguridad

Un contexto de seguridad es una política con nombre en el gateway: una deny_list y una lista ordenada de capabilities, cada una con un tool_pattern y, opcionalmente, path_allowlist, command_allowlist, subcommand_allowlist, domain_allowlist y max_response_size. Los agentes lanzados se ejecutan bajo aegis-system-agent-runtime, no bajo el contexto del nivel de la persona que los pidió. El orquestador fija el contexto al aprovisionar, y el agente "cannot escalate by claiming a different scp in its envelope" (no puede escalar declarando otro scp en su sobre).

Paso 4. El agente firma un mensaje canónico

La firma no se hace sobre el JSON en bruto. Se hace sobre tres claves, payload, security_token y timestamp, serializadas con las claves ordenadas en todos los niveles, sin espacios, con un timestamp Unix entero y en UTF-8. Cualquier otra secuencia de bytes da otra firma, y "the gateway will reject the envelope." (el gateway rechazará el sobre).

Paso 5. El agente envía el sobre

El sobre lleva protocol (siempre seal/v1), el security_token (un JWT emitido en la atestación, con una vida predeterminada de una hora), la signature Ed25519, el payload (en llamadas al estilo MCP, un tools/call de JSON-RPC), un container_id opcional y el timestamp. Va al endpoint de invocación del gateway, POST /v1/invoke. El gateway escucha por defecto en 8089; la API del propio orquestador de AEGIS está en 8088.

Paso 6. El gateway hace nueve comprobaciones

1. El campo protocol es seal/v1.
2. El token se decodifica en sus claims: sub, scp, wid, exec_id, iat, exp, jti.
3. La firma del token se verifica con la clave del gateway, comprobando explícitamente la cabecera alg.
4. El token no ha caducado.
5. Se encuentra la clave pública registrada del llamante para la sesión.
6. Se reconstruye el mensaje canónico.
7. La firma del sobre se verifica con esa clave y ese mensaje.
8. El timestamp está a menos de 30 segundos del reloj del servidor.
9. Se carga el contexto de seguridad nombrado en scp y se evalúa la llamada.

"Every check must pass before the payload is unwrapped and forwarded." (Todas las comprobaciones deben pasar antes de desenvolver y reenviar el payload.)

Paso 7. El contexto de seguridad decide

La evaluación sigue un orden fijo: si coincide un patrón de la deny_list, la llamada se rechaza; si no, "the first capability whose tool_pattern matches the tool name owns the decision" (la primera capacidad cuyo tool_pattern coincide con el nombre de la herramienta decide); si ninguna coincide, la llamada se rechaza, porque "there is no implicit allow." (no hay permiso implícito). Un patrón de familia como fs.* coincide con fs.read y nunca con fs ni con fsx.read.

Paso 8. La llamada se reenvía o se rechaza con un código

A una llamada permitida se le desenvuelve el payload y se envía a la herramienta; las credenciales, si la herramienta las necesita, se resuelven en ese momento. Una llamada rechazada responde con un código numérico: de 2000 a 2006 para políticas (no concedida, en la lista de denegación, ruta, comando o dominio fuera de su lista permitida, límite de tasa, ninguna capacidad coincidente), de 1001 a 1006 para firmas, tokens y sesiones, y de 3000 a 3002 para la atestación. El consejo de la documentación: "Switch on error.code, not on the status." (Decide según error.code, no según el estado.)

Paso 9. Cada decisión deja un evento de auditoría

El gateway publica ToolCallAuthorized o PolicyViolationBlocked, entre otros, con la firma, el timestamp y el jti del sobre, el sub, scp, wid y exec_id del token, el nombre de la herramienta, un resumen del payload ("payloads are not logged by default", los payloads no se registran por defecto) y la decisión con la regla que la tomó. Como solo la clave privada de la sesión pudo firmar el sobre, el registro da no repudio.

Paso 10. La sesión termina con la ejecución

Cuando la ejecución termina, por éxito, error, tiempo agotado o cancelación, el orquestador llama a DELETE /v1/seal/sessions/{session_id}. El gateway borra la clave, y un sobre capturado que se reenvíe después se rechaza.

Lo que la documentación deja abierto

• Límites de tasa. La página SEAL Protocol incluye "rate limit not exceeded" (límite de tasa no superado) entre las comprobaciones y un código 2005; la página Security Contexts dice que rate_limit está "reserved for a future enforcement phase" (reservado para una fase futura de aplicación). No se dice si hoy se aplica algún límite.
• Se dice que el reenvío después del cierre falla con session_not_found; la tabla de errores lo escribe 1005 SESSION_NOT_FOUND. No se muestra el cuerpo que recibe el cliente en ese caso.
• Estas páginas no dicen dónde se guardan los eventos de auditoría en un gateway independiente ni si PolicyViolationBlocked aparece en su tabla gateway_events.

Siguiente

Para encontrar estas llamadas en una ejecución real, lee Cómo leer el log de una ejecución de AEGIS. Para probarlo, AEGIS se instala con el comando que aparece en 100monkeys.ai:

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

Instala AEGIS desde 100monkeys.ai