Questa pagina è tradotta dalla documentazione inglese. Comandi, identificatori ed esempi restano invariati. Runtime 7.24.4 · SDK 2.6.7. Testo inglese

Modalità loop e compiti pianificati

Stato: Attivo Ambito: stato attuale Ultima revisione: 2026-08-27 Responsabile: runtime di ax-code

AX Code ha tre primitive di automazione componibili:

/loop — prompt ricorrenti

/loop <interval> <prompt>   start (interval like 30s, 5m, 1h)
/loop status                show runs, busy-skips, and the prompt
/loop stop                  stop the loop

Esempi:

/loop 5m check CI for new failures and fix any you find
/loop 30m drain the review queue

Regole:

• Limiti dell’intervallo: da 30 secondi a 24 ore. Un loop per sessione: avviarne uno nuovo sostituisce il vecchio.
• Un tick che scatta mentre la sessione è occupata viene saltato e contato, mai accodato: i loop non possono accumulare turni.
• Ogni tick è un turno di prompt ordinario: si applicano autorizzazioni, domande, tetti autonomi e soglie di completamento. Con l’autonomia spenta, un tick si ferma semplicemente alla prima richiesta di autorizzazione.
• Tetto rigido di 500 esecuzioni per loop, poi il loop si ferma da solo con un avviso.
• I loop vivono solo nel processo di backend: non sopravvivono a un riavvio. Per le pianificazioni durevoli, usa i compiti pianificati sotto.

Accoppiare /goal con /loop

/goal possiede l’obiettivo («tutti i test verdi, nessun rilievo di revisione aperto»); /loop fornisce il battito che continua a controllare. Creare prima un obiettivo esegue un redattore di piano dedicato che memorizza un contratto revisionabile sotto .ax-code/goals/ (o la directory dati di AX quando il progetto non è un worktree git). Se la pianificazione fallisce, l’obiettivo resta in pausa: /goal resume lo ritenta. I controlli di intervallo Git che misurano il diff di questo obiettivo usano l’HEAD del momento del piano ({BASELINE}), non origin/main, salvo che l’obiettivo nomini quel remoto. Il completamento dell’obiettivo resta subordinato alla verifica: l’agente non può marcare un obiettivo come completo dopo le modifiche senza un’esecuzione di verifica superata e, quando esiste un piano, deve anche fornire evidenza per ogni criterio di accettazione.

/goal keep main green: fix any CI failure the loop finds
/loop 10m check CI status and act on failures

L'assicurazione dell'obiettivo è su adesione

/goal <objective> parte subito: non allega un contratto di accettazione congelato, quindi il completamento è giudicato dal piano di lavoro che l’agente mantiene (attività in sospeso) più una verifica superata dopo l’ultima modifica. /goal view (e «View goal details» nella finestra dell’obiettivo) lo dice in modo esplicito — «No assurance contract» — così lo stato non è mai qualcosa che devi dedurre.

/goal --assure <objective> esegue prima il redattore del piano, che congela i criteri di accettazione, i riferimenti alle fonti e i controlli eseguibili; il completamento richiede allora anche una ricevuta corrente riuscita per ogni controllo obbligatorio (verify_project con il suo id goalCheck). Usalo quando il «fatto» dell’obiettivo deve essere dimostrabile, non solo descritto.

--assure si combina con i flag di budget in entrambi gli ordini (/goal --assure --budget 500000 <objective>). /goal replace <objective> conserva l’assicurazione quando l’obiettivo sostituito ha un contratto valido, così una sostituzione non può mai indebolire in silenzio un obiettivo che era già assicurato.

Budget e tetti dell'obiettivo

Un obiettivo attivo alza il tetto di auto-continuazione per esecuzione (session.max_continuations): l’esecuzione continua finché l’obiettivo non è completo, bloccato, in pausa o limitato dal budget. Che cosa lo limita invece:

• Budget di token (/goal --budget N …): quando si esaurisce, l’agente ottiene un turno di chiusura, poi l’obiettivo diventa budget_limited.
• Budget di tempo (/goal --time-budget 30m …): un limite di orologio in secondi, minuti (m) o ore (h), combinabile con il budget di token in entrambi gli ordini. Limita il lavoro trascorso che il budget di token non vede: lavori di addestramento remoti, chiamate di strumenti lunghe, stalli del provider. Si applicano lo stesso turno di chiusura e la transizione budget_limited quando scatta.
• Tetto cumulativo di passi: le esecuzioni con obiettivo attivo condividono il riparo Super-Long di max_steps × 40 passi totali (20,000 per impostazione predefinita) invece del tetto autonomo ordinario di max_steps × (max_continuations + 1). Sostituiscilo con session.max_total_steps.
• Il rilevamento dei cicli senza uscita, i tetti di raggio di impatto e l’interruttore dei turni solo di strumenti si applicano comunque per tutto il tempo.

CLI dell'obiettivo (senza interfaccia)

Lo stesso controllo dell’obiettivo è disponibile fuori dalla TUI sotto ax-code goal:

• ax-code goal status [--json] — mostra l’obiettivo corrente (-s/--session per scegliere una sessione; per impostazione predefinita l’unico obiettivo riprendibile del progetto, ed errore quando la scelta sarebbe ambigua).
• ax-code goal pause / ax-code goal clear — mettilo in pausa o cancellalo.
• ax-code goal resume — riprendi l’obiettivo e guidalo senza interfaccia finché non si assesta. Senza --attach avvia il progetto nel processo; con --attach http://localhost:4111 guida invece un server in esecuzione. I codici di uscita seguono il contratto dell’obiettivo senza interfaccia: 0 completo, 3 bloccato, 4 limitato dal budget, 6 in pausa o non terminale, 1 errore di sessione, 124 timeout di inattività (--idle-timeout-ms, predefinito 10 minuti). Gli eventi fluiscono su stdout come JSONL (--event-log PATH li registra anche), e una riga finale Goal <status>: <objective> va su stderr.

Quando un’esecuzione dell’obiettivo si avvicina al tetto di passi, l’agente riceve un avviso di convergenza una tantum che gli dice di verificare e completare l’obiettivo o lasciare un passaggio di consegne pulito. Se il tetto viene comunque raggiunto, l’obiettivo è in pausa — non fallito — e si può riprendere con /goal resume (alza prima session.max_total_steps se serve più margine).

Compiti pianificati — durevoli, conversazionali

Chiedilo direttamente all’agente; usa gli strumenti schedule_task, list_scheduled_tasks e manage_scheduled_task:

• «Ricordami alle 14:30 di controllare il deployment.»
• «Ogni giorno feriale alle 9, riassumi i nuovi fallimenti di CI.»
• «Elenca i miei compiti pianificati.» / «Metti in pausa il compito di riepilogo CI.»

Le modifiche di pianificazione create e gestite dall’agente richiedono l’autorizzazione schedule. Un’esecuzione in sola lettura non può cambiare né innescare una pianificazione. Per la creazione non presidiata senza interfaccia, usa il comando esplicito ax-code schedule oppure configura una concessione di autorizzazione esplicita schedule per l’agente; le concessioni jolly ampie non autorizzano le modifiche di pianificazione.

Gli stessi compiti si gestiscono dalla shell senza aprire la TUI:

ax-code schedule list                 # status, next run, schedule, id, title
ax-code schedule show <id>            # details plus the five most recent runs
ax-code schedule runs <id>            # run history: fired, failed, skipped and why
ax-code schedule pause|resume <id>
ax-code schedule delete <id>
ax-code schedule run <id>             # trigger now; requires a live runtime

pause/resume/delete passano dal runtime gestito del progetto quando uno è in esecuzione (effetto immediato, aggiornamenti vivi della TUI) e altrimenti scrivono direttamente il database del progetto. run ha bisogno di un backend vivo: avviane uno con ax-code runtime start, perché un processo CLI una tantum non deve rivendicare lavoro che non può finire. Tutti i sottocomandi di lettura accettano --json.

Le pianificazioni supportano esecuzioni una tantum, orari giornalieri o settimanali ed espressioni cron a 5 campi, ciascuna con un fuso orario IANA facoltativo. I compiti persistono nel database del progetto e scattano mentre un backend AX Code per il progetto è in esecuzione (scansione dello scheduler ogni 60s, presa atomica: un compito scatta una volta anche con più backend aperti). L’avanzamento della pianificazione e l’inserimento nella coda durevole condividono una transazione di database, così un crash non può far avanzare un’occorrenza senza lasciare lavoro da recuperare. I comandi una tantum come ax-code run e ax-code stats non rivendicano i compiti scaduti. Avvia un backend persistente con ax-code runtime start per inviarli.

Le occorrenze mancate usano per impostazione predefinita catchUpPolicy: "run_once": dopo un fermo, AX Code fonde qualsiasi arretrato in una sola esecuzione. Usa "skip" quando il lavoro stantio va avanzato senza essere eseguito. Un compito può anche impostare maxRunDurationMs da un secondo fino a 72 ore; un’esecuzione scaduta viene annullata e registrata come fallita.

Per il funzionamento attraverso riavvii di processo e di host, esegui il backend sotto un supervisore. Vedi Operazioni di lunga durata per gli esempi di systemd, launchd e PM2, più la semantica esatta di recupero.

Esecuzioni lunghe non presidiate

Per le sessioni autonome di molte ore, la modalità Super-Long aggiunge scadenze di esecuzione (fino a 72h), ritmo delle richieste e regolazione della compattazione. Si attiva da sola per i modelli le cui capacità dichiarate supportano il lavoro di agente lungo (modelli di ragionamento a contesto 1M, come Qwen 3.7+ Max/Plus sulle route Alibaba e GLM 5.x sulle route z.ai) e si può forzare per sessione, per progetto o tramite AX_CODE_SUPER_LONG. Il coinvolgimento dell’esecuzione viene registrato (super-long run engaged), e il ritmo del provider parte solo dopo una finestra di grazia dall’inizio dell’esecuzione (predefinito 2 ore, super_long.pacing_grace_minutes), così la fase iniziale produttiva di un’esecuzione agentica mantiene il pieno throughput delle chiamate di strumenti; la coda della maratona è ritmata secondo il livello di limite di frequenza dichiarato dal modello.