100monkeys.ai

Blog · Guida · 28 ottobre 2026

Il manifesto dell'agente AEGIS: ogni campo e cosa impone

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

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 la Agent Manifest Reference, la CLI Reference, la Workflow Manifest Reference e Human Approvals, e l'azienda l'ha rivista; questa edizione italiana è una traduzione della guida originale in inglese. Nomi dei campi, valori predefiniti e messaggi di rifiuto sono citati da quelle pagine, in inglese con la traduzione accanto.

AEGIS by 100monkeys.ai, in beta, esegue un agente a partire da un solo file YAML. La documentazione chiama il manifesto dell'agente "the source of truth for an Agent's identity, capabilities, security constraints, and execution requirements." (la fonte di verità per identità, capacità, vincoli di sicurezza e requisiti di esecuzione di un agente). Questa guida lo percorre sezione per sezione e dice, per ogni campo, che cosa ne fa l'orchestratore.

Passo 1. Scrivete l'intestazione

apiVersion: 100monkeys.ai/v1
kind: Agent
metadata:
  name: pr-reviewer
  version: "1.0.0"
  description: "Reviews pull request diffs and returns structured feedback."

apiVersion e kind devono avere esattamente questi valori. name deve rispettare ^[a-z0-9][a-z0-9-]{0,62}$, e la coppia name e version deve essere unica: distribuire di nuovo la stessa coppia fallisce a meno di passare --force. labels e annotations sono mappe chiave-valore facoltative per la ricerca e le note.

Passo 2. Scegliete un runtime

spec.runtime è l'unica parte obbligatoria di spec. Indicate language e version (python, javascript, typescript, rust o go, che si risolvono in un'immagine ufficiale) oppure una image completamente qualificata, mai entrambe; language senza version non è valido. image_pull_policy vale per default IfNotPresent. model indica un alias di modello di aegis-config.yaml, e un alias che genera immagini viene rifiutato. isolation accetta inherit, docker, firecracker e process; il riferimento segna docker come Fase 1 e gli altri due come Fase 2.

Passo 3. Dategli un compito

task.instruction è la guida con cui lavora l'agente, e impostarla "auto-enables semantic validation" (attiva automaticamente la validazione semantica). task.prompt_template è un template Handlebars; le sue variabili sono {{intent}}, {{instruction}}, {{input}}, {{iteration_number}}, {{previous_error}} e {{context}}. spec.input_schema, un JSON Schema con type: object, dichiara input con nome e li valida prima che l'agente venga eseguito.

Passo 4. Dichiarate solo l'accesso che serve

"All permissions are deny-by-default." (Tutti i permessi sono negati per impostazione predefinita.) Senza spec.security l'agente non ha rete né accesso al file system. network.mode è allow (solo la allowlist), deny (tutto tranne la denylist) oppure none, che "attaches no network interface to the container" (non collega alcuna interfaccia di rete al container). filesystem.read e filesystem.write elencano percorsi, glob ammessi. Le risorse valgono per default cpu: 1000 millicore, memory: "512Mi", disk: "1Gi" e timeout: "1800s", con un massimo di un'ora. Quando l'agente può tentare due volte o più, il timeout deve contenere due tentativi completi, 2 × (iteration_timeout + i timeout_seconds dei giudici) + 45 s, altrimenti l'agente "is refused on create and update" (viene rifiutato alla creazione e all'aggiornamento).

Passo 5. Montate i suoi volumi

Ogni voce di spec.volumes[] ha un name, una storage_class (ephemeral richiede ttl_hours; persistent richiede source.volume_id), un mount_path con radice in /workspace e un access_mode. L'accesso in lettura e scrittura a un volume persistente è esclusivo di un'esecuzione alla volta. Un volume che non si riesce a montare ferma l'iterazione: l'agente "never runs without its volume." (non viene mai eseguito senza il suo volume).

Passo 6. Definite come itera e cosa conta come finito

execution.mode è iterative (default) oppure one-shot. max_iterations va da 1 a 20, default 5, e max_retries è lo stesso campo. iteration_timeout vale per default 600s e llm_timeout_seconds 300. Dopo ogni tentativo, validation viene eseguita in ordine: exit_code, json_schema, regex, semantic (un agente giudice, min_score default 0.7) o multi_judge. Un fallimento torna all'agente come {{previous_error}}. tool_validation giudica ogni chiamata a strumento prima che venga eseguita; lì si usano solo voci semantic. outputs indica i file che l'esecuzione deve lasciare, ciascuno con min_bytes e magic facoltativi, e se ne manca uno il tentativo fallisce.

Passo 7. Concedete gli strumenti

spec.tools accetta stringhe come "mcp:filesystem" oppure oggetti con name, server e config. Per eseguire comandi, dichiarate executor: "builtin:cmd" con una subcommand_allowlist obbligatoria, una mappa da comando ai primi argomenti ammessi; qualsiasi altra chiamata "is rejected with a policy violation" (viene rifiutata con una violazione di policy). L'orchestratore verifica che le dichiarazioni possano fare il lavoro: un agente che deve scrivere file ma non dichiara strumenti, o che dichiara fs.write senza un volume in lettura e scrittura, viene rifiutato al deploy con una frase che ne indica il motivo.

Passo 8. Passate configurazione e segreti

I valori di spec.env sono un letterale, "secret:<name>" (iniettato da OpenBao e "never logged", mai registrato) oppure "config:<key>". spec.security_context è riservato agli operatori della piattaforma; un account consumer che lo imposta riceve 403 Forbidden.

Passo 9. Validate, poi distribuite

aegis agent deploy ./agent.yaml --validate-only
aegis agent deploy ./agent.yaml

--validate-only analizza e valida senza distribuire. aegis agent show <AGENT_ID> mostra il manifesto salvato.

Dove va un sì umano

Il manifesto dell'agente non ha un campo di approvazione. Il sì di una persona appartiene a un workflow, in uno stato kind: Human: prompt è obbligatorio, timeout vale per default 3600s e default_response è la risposta presa alla scadenza; senza di essa il workflow fallisce. Human Approvals dice che la transizione input_equals_yes di un gate accetta yes e che input_equals_no accetta no, e che una risposta che nessuna transizione accetta viene rifiutata e richiesta di nuovo.

Cosa la documentazione lascia aperto

Prossimo passo

Per eseguire un manifesto dall'inizio alla fine su un server nuovo, leggete Installare AEGIS su un VPS Ubuntu nuovo ed eseguire il primo task approvato. AEGIS si installa con il comando che compare su 100monkeys.ai:

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

Installa AEGIS da 100monkeys.ai