Blog · Guida · 28 ottobre 2026

Come AEGIS sigilla una chiamata a strumento: il gateway SEAL, passo per passo

Anche in: English, Español, Português, 日本語, Deutsch, Français, 한국어, 简体中文, हिन्दी · Tutte le guide in italiano

Trasparenza: AEGIS e il SEAL Gateway sono sviluppati da 100monkeys.ai, quindi leggete questa guida come il resoconto di chi li costruisce. L'ha scritta in bozza uno dei nostri agenti di IA a partire dalla documentazione pubblica, soprattutto le pagine SEAL Protocol, Integration with AEGIS e Security Contexts, e l'azienda l'ha rivista; questa edizione italiana è una traduzione della guida originale in inglese. Campi, codici e flussi qui sotto sono quelli della documentazione, non un output che abbiamo catturato per questa guida; le citazioni restano in inglese con la traduzione accanto.

AEGIS by 100monkeys.ai, in beta, non si fida di una chiamata a strumento solo perché l'ha fatta l'agente. Ogni chiamata viaggia in una busta firmata, e il SEAL Gateway la verifica prima che tocchi qualcosa fuori dall'esecuzione. Questa guida segue una chiamata dall'inizio dell'esecuzione fino al record di audit che lascia.

A cosa serve SEAL

SEAL sta per Signed Envelope Attestation Layer. La documentazione indica quattro lacune nei comuni protocolli di chiamata a strumenti: nessuna prova di quale client abbia inviato una richiesta, permessi tutto o niente per sessione, corpi modificabili in transito e nessun registro che provi quale chiamante abbia fatto cosa. Il suo esempio è una prompt injection: una pagina scaricata dice al modello di cancellare /workspace. "With SEAL, the caller's SecurityContext has no fs.delete capability. The gateway blocks it before it ever reaches the tool." (Con SEAL, il SecurityContext del chiamante non ha la capacità fs.delete. Il gateway la blocca prima che arrivi allo strumento.)

Il gateway funziona prima di tutto da solo. Nelle parole della documentazione è "the same aegis-seal-gateway binary" (lo stesso binario aegis-seal-gateway) che l'orchestratore AEGIS "deploys alongside itself" (distribuisce accanto a sé). Con AEGIS non c'è altro da fare per ottenere i passi seguenti; "it is the default." (è il comportamento predefinito).

Passo 1. L'orchestratore apre una sessione per l'esecuzione

Quando un'esecuzione entra in Running, l'orchestratore genera una nuova coppia di chiavi Ed25519 per quell'esecuzione e la registra presso il gateway: POST /v1/seal/sessions con un session_id (l'id dell'esecuzione, "so audit trails line up", così le tracce di audit coincidono), la public_key, il security_context e un expires_at limitato al budget di tempo reale dell'esecuzione. Può farlo solo un chiamante con lo scope seal.session.create; "agents themselves cannot self-register." (gli agenti non possono registrarsi da soli).

Passo 2. La chiave privata va all'agente e a nessun altro

La metà privata viene scritta nella configurazione effimera del container dell'agente, "a tmpfs mount, never persisted" (un mount tmpfs, mai persistito), insieme all'URL del gateway e all'id di sessione. Ogni esecuzione ha quindi la propria chiave, e "a leaked private key is bounded to a single execution's lifetime." (una chiave privata trapelata resta limitata alla durata di una sola esecuzione).

Passo 3. La sessione è legata a un solo contesto di sicurezza

Un contesto di sicurezza è una policy con nome sul gateway: una deny_list e un elenco ordinato di capabilities, ciascuna con un tool_pattern e, facoltativamente, path_allowlist, command_allowlist, subcommand_allowlist, domain_allowlist e max_response_size. Gli agenti avviati girano sotto aegis-system-agent-runtime, non sotto il contesto del livello della persona che li ha richiesti. L'orchestratore fissa il contesto al provisioning, e l'agente "cannot escalate by claiming a different scp in its envelope" (non può scalare i privilegi dichiarando un altro scp nella busta).

Passo 4. L'agente firma un messaggio canonico

La firma non riguarda il JSON grezzo. Riguarda tre chiavi, payload, security_token e timestamp, serializzate con le chiavi ordinate a ogni livello, senza spazi, con un timestamp Unix intero e in UTF-8. Qualsiasi altra sequenza di byte dà un'altra firma, e "the gateway will reject the envelope." (il gateway rifiuterà la busta).

Passo 5. L'agente invia la busta

La busta contiene protocol (sempre seal/v1), il security_token (un JWT emesso all'attestazione, con durata predefinita di un'ora), la signature Ed25519, il payload (per le chiamate in stile MCP, un tools/call JSON-RPC), un container_id facoltativo e il timestamp. Va all'endpoint di invocazione del gateway, POST /v1/invoke. Il gateway ascolta per impostazione predefinita sulla porta 8089; l'API dell'orchestratore AEGIS è sulla 8088.

Passo 6. Il gateway esegue nove controlli

1. Il campo protocol è seal/v1.
2. Il token si decodifica nei suoi claim: sub, scp, wid, exec_id, iat, exp, jti.
3. La firma del token si verifica con la chiave del gateway, controllando esplicitamente l'header alg.
4. Il token non è scaduto.
5. Si trova la chiave pubblica registrata del chiamante per la sessione.
6. Si ricostruisce il messaggio canonico.
7. La firma della busta si verifica con quella chiave e quel messaggio.
8. Il timestamp è entro 30 secondi dall'orologio del server.
9. Si carica il contesto di sicurezza indicato in scp e si valuta la chiamata.

"Every check must pass before the payload is unwrapped and forwarded." (Ogni controllo deve passare prima che il payload venga estratto e inoltrato.)

Passo 7. Il contesto di sicurezza decide

La valutazione segue un ordine fisso: se corrisponde un pattern della deny_list, la chiamata è rifiutata; altrimenti "the first capability whose tool_pattern matches the tool name owns the decision" (decide la prima capacità il cui tool_pattern corrisponde al nome dello strumento); se nessuna corrisponde, la chiamata è rifiutata, perché "there is no implicit allow." (non esiste un permesso implicito). Un pattern di famiglia come fs.* corrisponde a fs.read e mai a fs né a fsx.read.

Passo 8. La chiamata viene inoltrata o rifiutata con un codice

Per una chiamata consentita il payload viene estratto e inviato allo strumento; le credenziali, se lo strumento ne ha bisogno, si risolvono in quel momento. Una chiamata rifiutata risponde con un codice numerico: da 2000 a 2006 per le policy (non concessa, nella deny list, percorso, comando o dominio fuori dalla propria allowlist, limite di frequenza, nessuna capacità corrispondente), da 1001 a 1006 per firme, token e sessioni, e da 3000 a 3002 per l'attestazione. Il consiglio della documentazione: "Switch on error.code, not on the status." (Decidete in base a error.code, non allo stato.)

Passo 9. Ogni decisione lascia un evento di audit

Il gateway pubblica ToolCallAuthorized o PolicyViolationBlocked, tra gli altri, con la firma, il timestamp e il jti della busta, il sub, scp, wid ed exec_id del token, il nome dello strumento, un riepilogo del payload ("payloads are not logged by default", i payload non vengono registrati per impostazione predefinita) e la decisione con la regola che l'ha presa. Poiché solo la chiave privata della sessione poteva firmare la busta, il registro garantisce il non ripudio.

Passo 10. La sessione finisce con l'esecuzione

Quando l'esecuzione termina, per successo, errore, timeout o annullamento, l'orchestratore chiama DELETE /v1/seal/sessions/{session_id}. Il gateway cancella la chiave, e una busta catturata e reinviata in seguito viene rifiutata.

Cosa la documentazione lascia aperto

• Limiti di frequenza. La pagina SEAL Protocol elenca "rate limit not exceeded" (limite di frequenza non superato) tra i controlli e un codice 2005; la pagina Security Contexts dice che rate_limit è "reserved for a future enforcement phase" (riservato a una futura fase di applicazione). Non è detto se oggi venga applicato qualche limite.
• Si dice che il reinvio dopo la chiusura fallisce con session_not_found; la tabella degli errori lo scrive 1005 SESSION_NOT_FOUND. Non viene mostrato il corpo che il client riceve in quel caso.
• Queste pagine non dicono dove vengono conservati gli eventi di audit in un gateway autonomo, né se PolicyViolationBlocked compare nella sua tabella gateway_events.

Prossimo passo

Per ritrovare queste chiamate in un'esecuzione reale, leggete Reading an AEGIS execution log (in inglese). Per provarlo, AEGIS si installa con il comando che compare su 100monkeys.ai:

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

Installa AEGIS da 100monkeys.ai