Blog · Guida · 28 ottobre 2026

Come dare un passo di approvazione a un orchestratore: uno schema, con AEGIS come esempio

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

Trasparenza: AEGIS, l'esempio di questa guida, è sviluppato da 100monkeys.ai, quindi leggete le parti su AEGIS come il resoconto di chi lo costruisce. Lo schema in sé è generale e vale per qualsiasi orchestratore. L'ha scritta in bozza uno dei nostri agenti di IA a partire dalla documentazione pubblica di AEGIS e l'azienda l'ha rivista; questa edizione italiana è una traduzione della guida originale in inglese.

Un passo di approvazione è un punto di un'esecuzione automatica in cui il lavoro si ferma, una persona legge la cosa esatta che sta per accadere, e l'esecuzione prosegue solo con la risposta di quella persona. La maggior parte degli orchestratori sa fermarsi. Meno sono quelli in cui la pausa tiene davvero. Questo è lo schema che usiamo, passo per passo, con AEGIS by 100monkeys.ai, in beta, come esempio.

Lo schema in un paragrafo

Mettete il punto di controllo dopo che l'agente ha preparato l'atto e prima che l'atto avvenga. Mostrate al revisore la cosa preparata, non un suo riassunto. Decidete in anticipo che cosa significa il silenzio. Instradate esplicitamente entrambe le risposte. Lasciate rispondere il revisore da dove si trova già, e conservate la risposta nella storia dell'esecuzione. Limitate i tentativi, così una bozza respinta non può girare all'infinito.

Passo 1. Elencate gli atti che richiedono una persona

Non ogni passo ha bisogno di un'approvazione; approvare tutto insegna alle persone a cliccare senza leggere. Mettete il controllo sugli atti che escono dalla sandbox e non si possono annullare: inviare un messaggio a qualcuno all'esterno, fare merge su un branch protetto, spendere denaro, cancellare dati, pubblicare. Tutto il resto può girare con una policy scritta in anticipo. Il nostro documento Red levers chiama questi due tipi di arresto: limiti fissati prima dell'esecuzione e imposti dal runtime, e un'approvazione sull'atto, legata a un solo atto.

Passo 2. Dividete il lavoro dell'agente all'atto

Un agente che scrive e invia in un solo passo non si può fermare a metà. Dividetelo in uno stato che prepara e uno stato che agisce, così il controllo ha un posto dove stare. In AEGIS un workflow è una macchina a stati dichiarativa, e il controllo è uno stato a sé, kind: Human:

spec:
  initial_state: DRAFT
  states:
    DRAFT:
      kind: Agent
      agent: draft-agent
      transitions:
        - condition: on_success
          target: APPROVE
    APPROVE:
      kind: Human
      prompt: |
        About to send:
        {{DRAFT.output}}

        Approve? (yes/no)
      timeout: 86400s
      transitions:
        - condition: input_equals_yes
          target: SEND
        - condition: input_equals_no
          target: DISCARD

La forma segue la pagina Building Workflows della documentazione di AEGIS; draft-agent, SEND e DISCARD stanno per il vostro agente e i vostri stati.

Passo 3. Mettete davanti al revisore la cosa esatta

Il prompt è tutto ciò che il revisore vede, quindi inseritevi l'output preparato. I prompt di AEGIS accettano template della Blackboard: {{DRAFT.output}} qui sopra è l'output dello stato precedente, e la documentazione mostra anche punteggi di stati precedenti, come {{QUALITY_CHECK.output.score}}. Un revisore a cui si mostra "l'agente vuole inviare un'e-mail" approva una descrizione; un revisore a cui si mostra l'e-mail approva l'e-mail.

Passo 4. Decidete cosa significa il silenzio

Ogni controllo ha bisogno di un timeout e di una regola per quando scade. Nella pagina Human Approvals, timeout_seconds vale per default 3600. Con reject_on_timeout: false, il default, un controllo senza risposta fa fallire l'esecuzione con human_input_timeout. Con reject_on_timeout: true, il silenzio vale come un no e l'esecuzione prende la strada del rifiuto. Scegliete la seconda quando una risposta mancante deve essere un no pulito e non un errore. Non fate mai del silenzio un sì.

Una nota sui campi: la pagina Human Approvals usa timeout_seconds e le condizioni approved e rejected; la pagina Building Workflows usa timeout e input_equals_yes e input_equals_no. Usate una forma sola in modo coerente, e verificate la Workflow Manifest Reference per la versione che usate.

Passo 5. Instradate entrambe le risposte e limitate il ciclo

Un no è una risposta, non un errore da gestire dopo. Dategli uno stato di destinazione: scartare, oppure rimandare la bozza all'agente con il commento del revisore. Se rimandate un rifiuto allo stato di stesura, l'esecuzione ora ha un ciclo. AEGIS lo limita: max_state_visits per stato (default 5, massimo 20) e max_total_transitions per esecuzione (default 50, massimo 100). Impostateli sul numero di tentativi che un revisore è disposto a sopportare.

Passo 6. Lasciate rispondere il revisore da dove si trova

Un controllo che nessuno vede è un timeout. In AEGIS lo stesso controllo si può chiudere in tre modi:

• Dalla riga di comando: aegis workflow signal <execution-id> --response yes.
• Dal vostro client: elencate i controlli in attesa con GET /v1/workflow-gates?status=pending e rispondete a uno con POST /v1/workflows/executions/{id}/signal, con un corpo come { "response": "yes", "feedback": "Keep the flag name short." }.
• In Zaru Web: il controllo di un'esecuzione che avete avviato compare tra le vostre approvazioni in sospeso, con un pulsante per ogni parola consentita. La documentazione aggiunge che al companion di Zaru non viene offerto nessuno strumento che risponda a un controllo, in nessuna modalità, quindi il modello che ha preparato l'atto non può approvarlo.

Quest'ultima proprietà è quella da cercare in qualsiasi orchestratore: l'agente non deve avere la chiave del proprio controllo.

Passo 7. Conservate la risposta

Un'approvazione è una prova. Dopo che un controllo ha avuto risposta o è scaduto, AEGIS lo tiene in elenco: ?status=answered restituisce ogni controllo con la parola scelta, il commento, quando si è chiuso e che cosa ha fatto poi l'esecuzione. Registrate anche chi ha risposto: l'endpoint di approvazione della pagina Human Approvals accetta un campo approved_by, e un rifiuto richiede un reason.

Passo 8. Provate l'approvazione prima di fidarvi

Eseguite il workflow tre volte: rispondete sì, rispondete no, e lasciatelo scadere. Verificate che ogni strada arrivi dove volevate, e che niente dopo il controllo sia partito prima della risposta. Poi modificate la bozza dopo che il controllo è stato pubblicato e verificate che il revisore veda ciò che verrà davvero eseguito. Se il vostro orchestratore lega l'approvazione a una descrizione invece che al contenuto, è qui che lo scoprite.

Dove andare poi

Per provare lo schema dall'inizio alla fine su un vostro server, seguite Installare AEGIS su un VPS Ubuntu nuovo ed eseguire il primo task approvato. Per che cosa registrare e firmare attorno a ogni controllo, leggete Una checklist di tracciabilità per agenti di IA in produzione. Per la stessa idea di approvazione in un assistente personale, vedete Configurare un assistente Zaru che gestisce e-mail e calendario con le approvazioni.

Installa AEGIS da 100monkeys.ai