Blog · Guida · 28 ottobre 2026
Leggere un log di esecuzione AEGIS: cosa registra una chiamata di strumento sigillata
Trasparenza: AEGIS è sviluppato da 100monkeys.ai, quindi leggete questa guida come il resoconto di chi lo costruisce. L'ha scritta in bozza uno dei nostri agenti di IA a partire dalla documentazione pubblica di AEGIS, soprattutto Deploying & Running Agents, CLI Reference, SEAL Protocol e la pagina Observability del gateway, e l'azienda l'ha rivista; questa edizione italiana è una traduzione della guida originale in inglese. Righe di log, campi e codici qui sotto sono gli esempi della documentazione, non output che abbiamo catturato per questa guida.
AEGIS by 100monkeys.ai, in beta, esegue ogni agente nel proprio runtime isolato e manda le sue chiamate di strumenti attraverso un protocollo firmato chiamato SEAL. Questa guida legge un'esecuzione dall'esterno verso l'interno: il record dell'esecuzione, il log delle iterazioni, e poi che cosa registra lo strato SEAL su una singola chiamata, consentita o rifiutata.
Perché l'unità è l'esecuzione
La pagina Executions lo dice chiaramente: "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." (Ogni esecuzione è l'unità di osservabilità e di replay in AEGIS. Log, chiamate di strumenti, snapshot della blackboard e traiettorie di raffinamento sono tutti ancorati a un ID di esecuzione.) Ogni passo qui sotto parte da quell'id. Un'esecuzione gira nel ciclo "Execute, Evaluate, Refine" (eseguire, valutare, raffinare) e finisce "when the agent produces output that satisfies its evaluation criteria, when the iteration budget is exhausted, or when an unrecoverable failure occurs." (quando l'agente produce un output che soddisfa i suoi criteri di valutazione, quando il budget di iterazioni è esaurito, o quando si verifica un errore non recuperabile.)
Passo 1. Trovate l'id dell'esecuzione
aegis task execute lo stampa all'avvio (Execution started: <id>). Per le esecuzioni che non avete avviato voi, elencatele:
aegis task list
aegis task list --agent-id <AGENT_ID>
aegis task list --limit 20Un'esecuzione pianificata porta il proprio id nell'elenco delle esecuzioni della pianificazione; un'esecuzione di workflow compare in aegis workflow executions list.
Passo 2. Leggete il record dell'esecuzione
aegis task status <EXECUTION_ID> --output jsonSecondo la documentazione questo comando "returns the execution record, including status, start/end timestamps, total iterations, and each iteration's status and validation scores." (restituisce il record dell'esecuzione, con stato, orari di inizio e fine, numero totale di iterazioni, e stato e punteggi di validazione di ogni iterazione.) Leggete prima il numero di iterazioni. Una sola iterazione superata è un'esecuzione pulita; più iterazioni significano che l'output non ha superato la validazione ed è stato raffinato, e il log mostrerà perché.
Passo 3. Leggete il log delle iterazioni
aegis task logs <EXECUTION_ID>L'esempio della documentazione di ciò che stampa un'esecuzione, riga per riga:
[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)Leggetelo come tre tipi di riga: il ciclo di vita (avviata, completata), una riga Tool: per ogni chiamata fatta dall'agente, e una riga Validation: con il verdetto di ogni validatore e il punteggio. Aggiungete --errors-only per vedere solo i fallimenti, --verbose per più dettaglio e --follow per seguire un'esecuzione in corso. Per un workflow, aegis workflow logs <EXECUTION_ID> --transitions mostra solo i cambi di stato.
Passo 4. Sappiate cosa c'è dietro ogni riga Tool
Ogni riga Tool: è una chiamata passata per SEAL. "Every tool call is wrapped in a SealEnvelope" (Ogni chiamata di strumento è avvolta in una SealEnvelope): il protocollo (seal/v1), un security_token (un JWT emesso all'attestazione), una signature Ed25519, il payload (per le chiamate in stile MCP, un tools/call JSON-RPC), un container_id e un timestamp intero.
Sono le claim del token a legare la chiamata alla vostra esecuzione: sub (il chiamante), scp (il nome del contesto di sicurezza), wid (il workload) ed exec_id, che "ties every call in a session to one audit chain" (lega ogni chiamata di una sessione a un'unica catena di audit). Quindi l'id di esecuzione del passo 1 è la chiave che unisce la riga di log alla sua busta.
Passo 5. Leggete perché una chiamata è stata consentita
Il gateway esegue nove controlli prima di inoltrare una chiamata: il campo del protocollo, firma e scadenza del token, la chiave registrata del chiamante, la firma della busta su un messaggio canonico, un timestamp entro 30 secondi, e infine il contesto di sicurezza indicato in scp. Quest'ultimo controllo nega tutto ciò che è nella lista di esclusione, consente una chiamata solo quando una capacità corrisponde al suo strumento, percorso, dominio o sottocomando e al limite di frequenza, e altrimenti nega "(default deny)" (rifiuto per default). Il contesto non può cambiare a metà sessione: "callers cannot widen their context, switch contexts, or impersonate a different one." (i chiamanti non possono allargare il proprio contesto, cambiarlo o impersonarne un altro.)
Passo 6. Leggete un rifiuto
Una chiamata rifiutata non è un buco silenzioso nel log. Sul SEAL Gateway risponde con un codice numerico. Quelli che incontrerete più spesso:
- da
2000a2006: policy. Strumento non concesso, strumento nella lista di esclusione, percorso fuori dapath_allowlist, comando fuori dacommand_allowlist, dominio fuori dadomain_allowlist, limite di frequenza raggiunto, nessuna capacità corrispondente. 1003TOKEN_EXPIRED: il token è scaduto, il timestamp era fuori dalla finestra di 30 secondi, oppure iljtiera già stato visto, ed è così che si presenta una busta riprodotta.1001e1002: una firma malformata o che non si verifica.
La documentazione dice di "switch on error.code, not on the status" (decidere in base a error.code, non allo stato), e segnala una trappola: il POST /v1/seal/invoke dell'orchestratore risponde a un rifiuto con un codice testuale come TOOL_NOT_ALLOWED invece che con un numero.
Passo 7. Leggete il record di audit
La pagina SEAL Protocol elenca gli eventi prodotti da ogni chiamata, tra cui ToolCallAuthorized e PolicyViolationBlocked, e che cosa registra ciascuno: firma, timestamp e jti della busta; sub, scp, wid ed exec_id del token; il nome dello strumento e il "payload digest (not the full payload, payloads are not logged by default)" (digest del payload, non il payload completo: per default i payload non vengono registrati); e "the policy decision (ALLOW or DENY plus the deciding rule, if any)" (la decisione della policy, ALLOW o DENY, più la regola che ha deciso, se c'è). È la firma a dare il non ripudio: "only the holder of the ephemeral private key could have produced a valid signature." (solo chi possiede la chiave privata effimera avrebbe potuto produrre una firma valida.)
Su un SEAL Gateway autonomo quelle righe stanno nella tabella gateway_events. Non c'è ancora un endpoint REST per leggerle; la documentazione dà invece l'SQL:
SELECT event_type, created_at, payload
FROM gateway_events
WHERE payload->>'execution_id' = 'exec-1234' -- Postgres JSONB syntax
ORDER BY created_at;La tabella è solo in aggiunta, quindi inviatela al vostro SIEM interrogando gli id superiori all'ultimo che avete spedito.
Cosa la documentazione lascia aperto
- I due elenchi di eventi differiscono. La pagina SEAL Protocol nomina
PolicyViolationBlocked; la tabellagateway_eventsdel gateway, come la elenca Observability, no. Non è detto quale tabella contenga un rifiuto. - Le porte. La pagina SEAL mette l'orchestratore su
8080; la porta API predefinita della CLI è8088. - Il gateway non ha ancora un endpoint di metriche né tracce OTLP; lo dice la pagina Observability stessa.
Prossimo passo
Per ciò che serve a un revisore accanto a questi log, leggete Una checklist di tracciabilità per agenti di IA in produzione.