Blog · Guía · 28 de octubre de 2026

Cómo leer el log de una ejecución de AEGIS: qué registra una llamada a herramienta sellada

También en: English, Português, 日本語 · Todas las guías en español

Aviso: en 100monkeys.ai construimos AEGIS, 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 de AEGIS, sobre todo Deploying & Running Agents, la CLI Reference, la página SEAL Protocol y la página Observability del gateway, y la revisó la empresa; esta versión en español es una traducción de la guía original en inglés. Las líneas de log, campos y códigos son los ejemplos de la propia 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, ejecuta cada agente en su propio runtime aislado y envía sus llamadas a herramientas a través de un protocolo firmado llamado SEAL. Esta guía lee una ejecución de fuera hacia dentro: el registro de la ejecución, el log de iteraciones y después lo que la capa SEAL registra sobre una sola llamada a herramienta, permitida o rechazada.

Por qué la ejecución es la unidad

La página Executions lo dice sin rodeos: "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 ejecución es la unidad de observabilidad y de repetición en AEGIS. Los logs, las llamadas a herramientas, las instantáneas del blackboard y las trayectorias de refinamiento están todos anclados a un ID de ejecución.) Cada paso de abajo parte de ese id. Una ejecución recorre el bucle "Execute, Evaluate, Refine" (ejecutar, evaluar, refinar) y termina "when the agent produces output that satisfies its evaluation criteria, when the iteration budget is exhausted, or when an unrecoverable failure occurs" (cuando el agente produce una salida que cumple sus criterios de evaluación, cuando se agota el presupuesto de iteraciones o cuando ocurre un fallo irrecuperable).

Paso 1. Encuentra el id de ejecución

aegis task execute lo imprime al empezar (Execution started: <id>). Para las ejecuciones que no iniciaste tú, lístalas:

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

Una ejecución programada lleva su id de ejecución en la lista de ejecuciones de la programación; una ejecución de workflow aparece con aegis workflow executions list.

Paso 2. Lee el registro de la ejecución

aegis task status <EXECUTION_ID> --output json

La documentación dice que esto "returns the execution record, including status, start/end timestamps, total iterations, and each iteration's status and validation scores" (devuelve el registro de la ejecución, con el estado, las marcas de inicio y fin, el total de iteraciones y el estado y las puntuaciones de validación de cada iteración). Lee primero el número de iteraciones. Una iteración que pasó es una ejecución limpia; varias iteraciones significan que la salida no pasó la validación y se refinó, y el log mostrará por qué.

Paso 3. Lee el log de iteraciones

aegis task logs <EXECUTION_ID>

El ejemplo de la documentación de lo que imprime una ejecución, línea por línea:

[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)

Léelo como tres tipos de línea: el ciclo de vida (inicio, fin), una línea Tool: por cada llamada que hizo el agente y una línea Validation: con el veredicto de cada validador y la puntuación. Añade --errors-only para ver solo los fallos, --verbose para más detalle y --follow para seguir una ejecución en vivo. Para un workflow, aegis workflow logs <EXECUTION_ID> --transitions muestra solo los cambios de estado.

Paso 4. Qué hay detrás de cada línea Tool

Cada línea Tool: es una llamada que pasó por SEAL. "Every tool call is wrapped in a SealEnvelope" (cada llamada a herramienta va envuelta en un SealEnvelope): el protocolo (seal/v1), un security_token (un JWT emitido en la atestación), una signature Ed25519, el payload (para llamadas al estilo MCP, un tools/call JSON-RPC), un container_id y un timestamp entero.

Las claims del token son lo que liga la llamada a tu ejecución: sub (quien llama), scp (el nombre del contexto de seguridad), wid (la carga de trabajo) y exec_id, que "ties every call in a session to one audit chain" (liga cada llamada de una sesión a una sola cadena de auditoría). Así que el id de ejecución del paso 1 es la clave que une la línea del log con su sobre.

Paso 5. Lee por qué se permitió una llamada

El gateway hace nueve comprobaciones antes de reenviar una llamada: el campo de protocolo, la firma y la caducidad del token, la clave registrada de quien llama, la firma del sobre sobre un mensaje canónico, un timestamp dentro de 30 segundos y, por último, el contexto de seguridad nombrado en scp. Esa última comprobación deniega todo lo que esté en la lista de denegación, permite una llamada solo cuando una capacidad coincide con su herramienta, ruta, dominio o subcomando y su límite de frecuencia, y en otro caso deniega "(default deny)" (denegación por defecto). El contexto no puede cambiar a mitad de sesión: "callers cannot widen their context, switch contexts, or impersonate a different one" (quien llama no puede ampliar su contexto, cambiar de contexto ni hacerse pasar por otro).

Paso 6. Lee un rechazo

Una llamada rechazada no es un hueco silencioso en el log. En el SEAL Gateway responde con un código numérico. Los que verás más a menudo:

• 2000 a 2006: política. Herramienta no concedida, herramienta en la lista de denegación, ruta fuera de path_allowlist, comando fuera de command_allowlist, dominio fuera de domain_allowlist, límite de frecuencia alcanzado, ninguna capacidad coincidió.
• 1003 TOKEN_EXPIRED: el token caducó, el timestamp quedó fuera de la ventana de 30 segundos o el jti ya se había visto, que es como aparece un sobre repetido.
• 1001 y 1002: una firma mal formada o que no se verifica.

La documentación dice "switch on error.code, not on the status" (decide según error.code, no según el estado) y avisa de una trampa: el propio POST /v1/seal/invoke del orquestador responde a un rechazo con un código de texto como TOOL_NOT_ALLOWED en lugar de un número.

Paso 7. Lee el registro de auditoría

La página SEAL Protocol enumera los eventos que produce cada llamada, entre ellos ToolCallAuthorized y PolicyViolationBlocked, y lo que captura cada uno: la firma, el timestamp y el jti del sobre; los sub, scp, wid y exec_id del token; el nombre de la herramienta y el "payload digest (not the full payload, payloads are not logged by default)" (resumen del payload, no el payload completo; los payloads no se registran por defecto); y "the policy decision (ALLOW or DENY plus the deciding rule, if any)" (la decisión de política, ALLOW o DENY, más la regla que decidió, si la hay). La firma es lo que da el no repudio: "only the holder of the ephemeral private key could have produced a valid signature" (solo quien tiene la clave privada efímera pudo producir una firma válida).

En un SEAL Gateway independiente esas filas viven en la tabla gateway_events. Todavía no hay endpoint REST para ellas; la documentación da SQL en su lugar:

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

La tabla solo admite añadir filas, así que envíala a tu SIEM consultando los ids mayores que el último que enviaste.

Lo que la documentación deja abierto

• Las dos listas de eventos no coinciden. La página SEAL Protocol nombra PolicyViolationBlocked; la tabla gateway_events del gateway, tal como la lista Observability, no. No se dice qué tabla guarda una denegación.
• Puertos. La página de SEAL pone el orquestador en 8080; el puerto de API por defecto de la CLI es 8088.
• El gateway todavía no tiene endpoint de métricas ni trazas OTLP; la propia página Observability lo dice.

Hacia dónde seguir

Para saber qué necesita quien revisa además de estos logs, lee Lista de trazabilidad para agentes de IA en producción.

Instala AEGIS desde 100monkeys.ai