100monkeys.ai

Blog · Guida · 29 ottobre 2026

Stati e transizioni di un workflow AEGIS, passo per passo

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 Workflow Manifest Reference e la CLI Reference, e l'azienda l'ha rivista; questa edizione italiana è una traduzione della guida originale in inglese. Ogni riga YAML e ogni comando qui sotto sono copiati da quelle pagine; nessuno è stato eseguito per questa guida. Le citazioni restano in inglese con la traduzione accanto. Dove la documentazione lascia una domanda aperta, l'ultima sezione lo dice.

AEGIS by 100monkeys.ai, in beta, esegue un workflow come una macchina a stati finiti scritta in un solo file YAML. La documentazione di riferimento lo chiama "a durable, restartable sequence" (una sequenza durevole e riavviabile) che coordina agenti, container, comandi di sistema e varchi di approvazione umana. Questa guida scrive uno stato alla volta e mostra come il motore sceglie il successivo.

Passo 1. Scrivete l'intestazione

apiVersion: 100monkeys.ai/v1
kind: Workflow

metadata:
  name: dev-pipeline
  version: "1.0.0"

apiVersion deve essere esattamente 100monkeys.ai/v1 e kind esattamente Workflow. name segue ^[a-z0-9][a-z0-9-]{0,62}$ e la coppia di nome e versione deve essere unica: sovrascrivere una versione esistente richiede il parametro force. metadata.input_schema è facoltativo; se c'è, l'input del chiamante viene validato prima che l'esecuzione parta, e un payload che non passa è "rejected with HTTP 422; no workflow execution is created." (rifiutato con HTTP 422; non viene creata alcuna esecuzione del workflow).

Passo 2. Nominate il primo stato e i limiti

Sotto spec, initial_state è obbligatorio e deve esistere in spec.states. Due limiti fermano un ciclo che non finisce mai. spec.max_total_transitions vale 50 per impostazione predefinita, con un tetto di 100, oltre il quale "the workflow terminates" (il workflow termina). max_state_visits di ogni stato vale 5 per impostazione predefinita, con un tetto di 20. Ogni stato ha anche un timeout, 300s per impostazione predefinita. spec.context contiene costanti che ogni stato legge come {{workflow.context.KEY}}, per esempio un limite di iterazioni o una soglia.

Passo 3. Scegliete un tipo per ogni stato

Ogni stato indica un kind. La documentazione ne elenca otto:

Passo 4. Scrivete le transizioni nell'ordine in cui volete provarle

Le transizioni sono "evaluated top-to-bottom. The first matching transition is taken." (valutate dall'alto in basso; si prende la prima che corrisponde). Ognuna indica uno stato target e, facoltativamente, una condition. Questo stato System, preso dall'esempio della documentazione stessa, ramifica sul codice di uscita:

    EXECUTE:
      kind: System
      command: python main.py
      env:
        CODE: "{{GENERATE.output}}"
        PYTHONPATH: /workspace
      transitions:
        - condition: exit_code_zero
          target: VALIDATE
        - condition: exit_code_non_zero
          target: REFINE
          feedback: "Execution failed: {{EXECUTE.output.stderr}}"

Le condizioni che ogni tipo può usare: on_success e on_failure per la maggior parte dei tipi; exit_code_zero, exit_code_non_zero ed exit_code con un value per System e ContainerRun; input_equals, input_equals_yes e input_equals_no per Human; consensus, all_approved e any_rejected per ParallelAgents; custom con una expression Handlebars per qualsiasi tipo; e always, o nessuna condizione, come ripiego incondizionato. Il consiglio della documentazione: "Always include an unconditional fallback as the last transition." (includete sempre un ripiego incondizionato come ultima transizione).

Passo 5. Ramificate su un punteggio

    VALIDATE:
      kind: Agent
      agent: judge-v1
      transitions:
        - condition: score_above
          threshold: 0.95
          target: COMPLETE
        - condition: score_below
          threshold: 0.95
          target: REFINE
          feedback: "{{VALIDATE.output.reasoning}}"

Entrambi i confronti sono stretti, quindi un punteggio di esattamente 0.95 non prende nessuna delle due transizioni qui sopra. Il punteggio si legge da score dello stato, altrimenti da final_score, altrimenti da consensus.score. Uno stato senza punteggio non corrisponde a nessuna delle due, e se nient'altro corrisponde l'esecuzione fallisce con State "<name>" carries no score for its score transitions. Per uno stato Agent, score_between accetta min e max inclusivi.

Passo 6. Portate ciò che è successo nello stato successivo

La stringa feedback di una transizione diventa {{state.feedback}} nello stato a cui porta: è così che un messaggio di errore arriva all'agente che riprova. Ogni stato concluso viene scritto sulla Blackboard sotto il suo nome, quindi gli stati successivi leggono {{EXECUTE.output.stdout}} o {{VALIDATE.score}}. Tenete separati due spazi di nomi: {{input.KEY}} è ciò che il chiamante ha passato e "is immutable" (è immutabile), mentre {{blackboard.KEY}} cresce man mano che l'esecuzione procede. Un template che nomina una chiave che nessuno stato ha ancora scritto produce un segnaposto visibile, ERROR: missing key con il nome dello stato, invece di una stringa vuota.

Passo 7. Iterate con una guardia e chiudete l'esecuzione

    REFINE:
      kind: System
      command: update_context
      env:
        ITERATION: "{{blackboard.iteration_number + 1}}"
        ERRORS: "{{state.feedback}}"
      transitions:
        - condition: custom
          expression: "{{blackboard.iteration_number < workflow.context.max_iterations}}"
          target: GENERATE
        - condition: custom
          expression: "{{blackboard.iteration_number >= workflow.context.max_iterations}}"
          target: FAILED

    COMPLETE:
      kind: System
      command: finalize
      transitions: []

Uno stato con transitions: [] è terminale: "When reached, the workflow execution completes with status completed." (quando viene raggiunto, l'esecuzione del workflow si conclude con stato completed). Date al ciclo una sua guardia sulla Blackboard, come sopra, oltre a contare su max_state_visits.

Passo 8. Validate, distribuite, eseguite e osservate le transizioni

aegis workflow validate ./pipeline.yaml
aegis workflow deploy ./pipeline.yaml
aegis workflow run dev-pipeline --input '{"task": "..."}'
aegis workflow logs <execution_id> --transitions

validate controlla il manifesto in locale; deploy lo registra e fallisce su un nome e una versione già esistenti, a meno che non aggiungiate --force; logs --transitions mostra "state entries/exits only" (solo ingressi e uscite degli stati), il modo più rapido per vedere quale ramo ha preso ogni stato.

Cosa lascia aperto la documentazione

E poi

Per lo stato Human in dettaglio, con ciò che vede chi approva e cosa significa il silenzio, leggete Come dare un passo di approvazione a un orchestratore. AEGIS si installa con il comando stampato su 100monkeys.ai:

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

Installa AEGIS da 100monkeys.ai