Blog · Guida · 28 ottobre 2026

Eseguire un agente pianificato con AEGIS: pianificazioni, esecuzioni e cosa vedete quando una fallisce

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 pagina Schedules e il riferimento Schedule Tools, e l'azienda l'ha rivista; questa edizione italiana è una traduzione della guida originale in inglese. Ogni campo, route e messaggio qui sotto è citato da quelle pagine, in inglese con la traduzione accanto. Per questa guida non abbiamo eseguito queste chiamate, e dove la documentazione lascia aperto un passo lo diciamo.

AEGIS by 100monkeys.ai, in beta, è un orchestratore self-hosted che esegue agenti autonomi in runtime isolati e governati da policy. Questa guida mette uno dei vostri agenti su un timer, rilegge che cosa ha fatto ogni avvio e mostra i quattro esiti possibili, così un'esecuzione che non è avvenuta è visibile quanto una che è avvenuta.

Che cos'è una pianificazione

La documentazione la definisce in una frase: "A schedule starts one of your agents or workflows as you, either once at a time you choose or again and again on a recurrence." (Una pianificazione avvia uno dei vostri agenti o workflow a vostro nome, una volta all'ora che scegliete oppure più volte con una ricorrenza.) Ne seguono tre conseguenze, e ciascuna dà forma ai passi qui sotto.

• Una pianificazione è un vostro oggetto, "never a field of the agent or workflow it runs" (mai un campo dell'agente o del workflow che esegue).
• Gira a nome di una persona. "A schedule always runs as a person. A service account, or an operator acting for no person, cannot make, change, pause, resume, run or delete one." (Una pianificazione gira sempre come una persona. Un account di servizio, o un operatore che non agisce per una persona, non può crearne, modificarne, metterne in pausa, riprenderne, eseguirne o cancellarne una.)
• Ogni avvio è un'esecuzione ordinaria. "At each fire the orchestrator starts the run exactly as aegis.task.execute or aegis.workflow.run would for you, with the schedule's intent, input and connections." (A ogni avvio l'orchestratore fa partire l'esecuzione esattamente come farebbero per voi aegis.task.execute o aegis.workflow.run, con l'intento, l'input e le connessioni della pianificazione.)

Passo 1. Scegliete l'agente e i tempi

Usate un agente che avete già eseguito una volta a mano con aegis task execute <AGENT>, così sapete com'è un'esecuzione riuscita.

Poi scegliete uno dei due tempi. Ne indicate esattamente uno.

• Una volta: at, un orario RFC 3339 "at least one minute from now and at most a year ahead" (almeno un minuto da adesso e al massimo un anno avanti).
• Ricorrente: recurrence con cron, timezone e jitter_seconds. Il cron ha cinque campi (minuto, ora, giorno del mese, mese, giorno della settimana), "no seconds field and no @daily-style shorthand" (nessun campo dei secondi e nessuna abbreviazione in stile @daily). Il fuso orario è un nome IANA e vale per default UTC. Il jitter ritarda ogni esecuzione di un tempo casuale fino a quel numero di secondi, al massimo 3600.

Due limiti di cui tenere conto: "A schedule runs at most once every 5 minutes" (una pianificazione gira al massimo una volta ogni 5 minuti), e potete avere al massimo 25 pianificazioni non cancellate.

Passo 2. Scegliete cosa può raggiungere l'esecuzione

Un'esecuzione pianificata raggiunge solo le connessioni indicate dal suo profile o dai suoi contexts, e "a schedule with neither reaches none of your connections." (una pianificazione senza nessuno dei due non raggiunge nessuna delle vostre connessioni.) Una pianificazione porta l'uno o l'altro, mai entrambi. Se il vostro agente legge la posta o un repository, indicate ora il profilo; altrimenti l'avvio verrà rifiutato per una connessione mancante, e il rifiuto lo dirà.

Passo 3. Create la pianificazione

Nella CLI Reference non c'è un comando shell aegis schedule. Una pianificazione si crea con la route REST POST /v1/schedules (scope schedule:write), con lo strumento MCP aegis.schedule.create, oppure dalla pagina Schedules di Zaru. Lo strumento accetta questi argomenti, come li elenca il riferimento:

aegis.schedule.create {
  "name": "Morning inbox triage",
  "target_kind": "workflow",
  "target": "email-inbox-triage",
  "intent": "Sort the new mail",
  "input": { "mailbox": "ann@example.com" },
  "recurrence": { "cron": "*/30 * * * *", "timezone": "UTC", "jitter_seconds": 300 }
}

Quell'esempio è la pianificazione della documentazione stessa. Cambiate target_kind in agent e target nel nome del vostro agente. La risposta è {"schedule": {...}} con il suo state, next_run_at e last_run. Rileggete next_run_at prima di andarvene.

Passo 4. Avviatela una volta, subito

Non aspettate il primo orario pianificato per sapere se funziona. Il proprietario può avviare subito un'esecuzione con POST /v1/schedules/{id}/run o aegis.schedule.run_now. Gira "exactly as a fire starts it: as the owner, with the schedule's target, input, connections or profile, and attachments" (esattamente come la avvia un avvio pianificato: come il proprietario, con target, input, connessioni o profilo e allegati della pianificazione), e "nothing else changes" (nient'altro cambia): la pianificazione mantiene stato e tempi.

Passo 5. Leggete le esecuzioni

aegis.schedule.runs { "schedule_id": "<id>", "limit": 20 }

La route è GET /v1/schedules/{id}/runs?limit=. Le esecuzioni arrivano dalla più recente, ciascuna con scheduled_time (null per un'esecuzione avviata subito), fired_at, outcome, detail ed execution (il suo id, kind e status). Portate l'id di esecuzione nella CLI per leggere l'esecuzione stessa: aegis task logs <EXECUTION_ID>, con --errors-only quando volete solo i fallimenti.

Passo 6. Conoscete i quattro esiti

Ogni avvio viene registrato una volta per orario pianificato, quindi un avvio che Temporal ripete "answers the first fire's record instead of starting a second run" (risponde con il record del primo avvio invece di far partire una seconda esecuzione). Ogni record ha un solo esito:

• started: l'esecuzione è partita, e l'avvio registra il suo id di esecuzione.
• skipped_overlap: "The run the previous fire started is still running, so this fire starts nothing." (L'esecuzione avviata dall'avvio precedente è ancora in corso, quindi questo avvio non fa partire nulla.) Zaru lo mostra come "Skipped: the last run was still running" (Saltata: l'ultima esecuzione era ancora in corso).
• skipped_paused: la pianificazione è in pausa.
• refused: "The run could not start. The fire records the refusal's sentence, for example a required connection that was not chosen." (L'esecuzione non è potuta partire. L'avvio registra la frase del rifiuto, per esempio una connessione richiesta che non era stata scelta.)

Un esito started dice che l'esecuzione è cominciata, non che è riuscita. Lo stato dell'esecuzione è in execution.status, e il motivo di un fallimento è nei suoi log.

Passo 7. Sappiate cosa succede quando gli avvii continuano a fallire

"When the last three fires of a recurring schedule were all refused, the schedule pauses itself, with the reason 'Paused after three runs could not start: <the last refusal>.'" (Quando gli ultimi tre avvii di una pianificazione ricorrente sono stati tutti rifiutati, la pianificazione si mette in pausa da sola, con il motivo indicato.) Leggete paused_reason sulla pianificazione, correggete la causa, poi riprendete con aegis.schedule.resume. Un avvio perso mentre l'orchestratore si riavvia "is still made up to 10 minutes late; later than that, the time is skipped." (viene ancora recuperato fino a 10 minuti di ritardo; oltre, quell'orario viene saltato.)

Passo 8. Le approvazioni valgono ancora

Un'esecuzione pianificata agisce a vostro nome, "so every tool call that waits for your approval in a conversation waits for it in a scheduled run too" (quindi ogni chiamata di strumento che in una conversazione aspetta la vostra approvazione la aspetta anche in un'esecuzione pianificata). In Zaru la richiesta compare nella pagina Approvals con la dicitura "From your schedule <name>" (dalla vostra pianificazione <nome>).

Cosa la documentazione lascia aperto

• Un comando shell. La CLI Reference non elenca nessun sottocomando per le pianificazioni, quindi chi fa self-hosting usa le route REST o un client MCP.
• Chi siete "voi" sullo stack locale. Le pianificazioni girano come una persona e richiedono schedule:write, mentre lo stack di aegis init gira senza IAM. La documentazione non dice a chi appartenga lì una pianificazione; non l'abbiamo provato.

Prossimo passo

Per mettere una persona tra l'agente pianificato e qualsiasi cosa invii, leggete Come dare un passo di approvazione a un orchestratore. Per leggere che cosa ha fatto un'esecuzione, leggete Leggere un log di esecuzione AEGIS.

Installa AEGIS da 100monkeys.ai