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

Modalità autonoma

Stato: attivo Ambito: stato attuale Ultima revisione: 2026-08-25 Responsabile: runtime di ax-code

La modalità autonoma consente ad AX Code di completare i compiti senza attendere la conferma umana a ogni passo a basso rischio. Quando è abilitata, i prompt di permesso vengono approvati automaticamente salvo che siano bloccati in modo esplicito, e le finestre di domanda ricevono una risposta automatica con un’euristica di buona pratica che privilegia scelte raccomandate, predefinite, comuni, semplici e minime, evitando opzioni rischiose o sovraingegnerizzate.

Per impostazione predefinita, la modalità autonoma è attiva. Se l’hai disattivata in precedenza, quella preferenza viene salvata e ripristinata all’avvio successivo.

Avvio rapido

Attiva o disattiva dalla TUI:

• Digita /autonomous nel prompt, oppure
• Premi Ctrl+P e cerca «autonomo», oppure
• Fai clic sull’indicatore autonomo acceso/spento nella barra di stato

La barra di stato mostra lo stato corrente:

• autonomo attivo (sfondo giallo, testo rosso in grassetto) — l’agente gira senza pause
• autonomo spento (testo verde) — l’agente si ferma per i prompt di permesso e di domanda

L’impostazione persiste tra le sessioni in ax-code.json.

Che cosa cambia

Come funziona

La modalità autonoma opera su tre strati:

Fonte di verità

Questa pagina riassume il comportamento visibile all’utente. Quando il comportamento cambia, verifica la documentazione rispetto a:

• packages/ax-code/src/session/processor.ts per l’approvazione automatica dei permessi, il comportamento del ciclo, la gestione dei rifiuti e i tetti autonomi.
• packages/ax-code/src/session/system.ts e i file di prompt del provider sotto packages/ax-code/src/session/prompt/ per le istruzioni del flusso di lavoro autonomo.
• packages/ax-code/src/question/ e packages/ax-code/test/question/question.test.ts per le euristiche di risposta automatica alle domande e il comportamento di escalation.
• packages/ax-code/src/session/blast-radius.ts per i tetti di passi e di modifiche ai file autonomi.
• packages/ax-code/test/session/system.test.ts, packages/ax-code/test/session/prompt.test.ts e i test di sessione correlati per il comportamento del prompt e del registro delle decisioni.

Mantieni le garanzie di sicurezza qui allineate alla documentazione della sandbox; la modalità autonoma cambia il comportamento di approvazione, non l’applicazione dell’isolamento.

1. Approvazione automatica dei permessi (lato server)

La modalità autonoma usa una policy ibrida che nega per prima (ADR-004 / PRD v4.2.0). Quando uno strumento chiama ctx.ask() per un permesso, il modulo Permission classifica il permesso:

• I permessi SAFE (read, glob, grep, list, lsp, code_intelligence, skill, todoread) si approvano automaticamente senza creare un prompt bloccante.
• I permessi RISK (edit, bash, external_directory, task, webfetch, websearch, codesearch, …) passano al ruleset: le regole di consenso e negazione configurate dell’agente si applicano ancora, e le regole di negazione definite dall’utente vengono sempre applicate. Nella modalità sandbox full-access, i permessi RISK vengono approvati automaticamente dopo la valutazione delle regole di negazione.
• I permessi sconosciuti chiedono per impostazione predefinita (experimental.autonomous_strict_permission: false conserva il comportamento legacy di consenso).

Permessi che arrivano sempre a una decisione per chiamata invece di un’approvazione immediata basata su regole: isolation_escalation (richieste di override della sandbox), i permessi INTERACTIVE_ONLY e l’insieme NEVER_AUTONOMOUS_AUTOAPPROVE. Una restrizione (ADR-098): nella modalità sandbox full-access, le richieste external_directory marcate solo interattive — comandi bash i cui percorsi non possono essere verificati staticamente perché usano un glob, una variabile o un’espansione a parentesi graffe — vengono anch’esse approvate automaticamente, perché una sandbox ad accesso completo non ha più un confine di filesystem da proteggere. Le regole di negazione esplicite si applicano ancora, e le modalità con sandbox attiva (workspace-write, read-only) mantengono il prompt per chiamata.

«Consenti una volta» in inattività (attivo per impostazione predefinita): Auto attivo più Sandbox spento (full-access) significa interazione minima: ogni permesso in attesa può rispondere automaticamente una volta dopo 15 secondi, inclusi requireInteractive, i prompt di hook e di escalation della sandbox. Auto spento o Sandbox attivo richiede una risposta umana ai prompt in attesa. WebMCP richiede in più che il ponte corrispondente sia connesso; un altro ponte connesso non basta. Le regole di negazione esplicite si applicano ancora. experimental.permission_idle_once.enabled: false disabilita i conti alla rovescia, e permissions può restringerne l’ambito. L’impostazione legacy timeout_ms è accettata per compatibilità ma non cambia più la durata fissa di 15 secondi.

Il server possiede il conto alla rovescia. La richiesta più vecchia di ogni sessione riceve una scadenza; le richieste in coda ricevono 15 secondi nuovi quando arrivano in testa. Le risposte umane annullano il timer. Disattivare Auto, attivare Sandbox o disconnettere il ponte WebMCP rilevante annulla i conti alla rovescia in attesa. Ripristinare l’idoneità avvia un conto alla rovescia nuovo. Le lacune temporanee di ricaricamento della configurazione sospendono il conto alla rovescia. Le risposte automatiche ricontrollano la modalità corrente, il ponte e le regole di negazione e non salvano mai un’approvazione persistente. L’override interno di debug e test AX_CODE_PERMISSION_IDLE_ONCE_MS resta disponibile ed è limitato al massimo del timer di Node.js.

Le modalità sono limitate alla directory attiva. Un ax-code.json annidato può scavalcare le impostazioni della radice del repository; usa l’interruttore Sandbox della sessione attiva per cambiarne la modalità effettiva.

Percorsi protetti non scavalcabili: la modalità autonoma rifiuta anche di scrivere un insieme fisso di percorsi del piano di policy e controllo — ax-code.json/ax-code.jsonc, .ax-code/**, .git/config e .git/refs/** — così l’agente non può modificare la propria configurazione, alzare i propri tetti di autonomia o piantare hook git. A differenza dell’elenco configurabile dei percorsi bloccati, questi non possono essere rimossi dalla configurazione di progetto o utente.

2. Risposta automatica alle domande (lato server)

Quando uno strumento pone una domanda all’utente, il modulo Question sceglie subito una risposta. Privilegia le opzioni marcate come raccomandate, predefinite, sicure, standard, comuni, convenzionali, buona pratica, semplici o minime. Evita le opzioni marcate sperimentali, rischiose, pericolose, distruttive, avanzate, complesse, di riscrittura o sovraingegnerizzate. Se nessuna opzione ha un segnale, sceglie la prima perché lo strumento di domanda istruisce gli agenti a mettere per prima l’opzione raccomandata.

3. Ciclo del processore (livello sessione)

Se un permesso viene in qualche modo rifiutato (per esempio da una regola di negazione esplicita), il ciclo del processore non si ferma: continua al passo successivo invece di arrestare la sessione.

4. Quadro decisionale in stile PRD/ADR

La modalità autonoma aggiunge un promemoria di flusso di lavoro leggero al prompt di sistema. Prima dell’implementazione, l’agente dovrebbe inquadrare il lavoro con problema, vincoli, decisione, compromessi, piano e validazione. Per modifiche sostanziali su più file, architetturali o visibili nel prodotto, può creare o aggiornare un documento del repository quando ciò corrisponde allo schema di documentazione del repository. Per le modifiche banali, dovrebbe tenere questo quadro leggero nel piano per evitare la sovraingegnerizzazione.

Autonomo e sandbox

La modalità autonoma e la modalità sandbox sono indipendenti. Puoi usarle insieme:

La postura predefinita del runtime è autonomo acceso più sandbox spento: full-access con la rete abilitata. Questo dà il comportamento CLI con meno attrito ma nessun confine di isolamento. Usa /sandbox, --sandbox workspace-write, AX_CODE_ISOLATION_MODE o la configurazione di progetto per abilitare restrizioni per lavoro non fidato o non presidiato.

Configurazione

File di configurazione

In ax-code.json:

{
  "autonomous": true
}

Imposta su false per disabilitare:

{
  "autonomous": false
}

Variabile d'ambiente

AX_CODE_AUTONOMOUS=true ax-code    # force autonomous on
AX_CODE_AUTONOMOUS=false ax-code   # force autonomous off

Precedenza

Variabile d’ambiente > file di configurazione > predefinito (attivo)

Budget di carico (turni del modello e chiamate di strumenti)

La modalità autonoma non significa esecuzione illimitata. Si applicano diversi tetti indipendenti. I predefiniti sotto sono le costanti distribuite; alzali o abbassali in ax-code.json quando un carico ha bisogno di più spazio.

Un turno del modello è una richiesta di modello del ciclo esterno. Una chiamata di strumento è un’invocazione di strumento dentro un turno del modello. Sono budget separati: un solo turno del modello può emettere più chiamate di strumenti. I nomi di configurazione legacy che contengono steps restano supportati, ma non rendono intercambiabili le due unità.

Preferisci l’oggetto di prima classe autonomy. Le chiavi legacy session.* e experimental.autonomous_caps.* funzionano ancora come alias (precedenza più bassa).

I file binari (cp di un eseguibile, curl -o di uno zip e altre scritture non testuali) contano ancora verso il tetto dei file, ma addebitano zero righe. Il tetto delle righe misura il cambiamento testuale. Le scritture di testo della shell conservano la stima ceil(size / 80) così un payload denso non può eludere il budget avendo pochi newline.

I percorsi non tracciati che git check-ignore segnala come ignorati addebitano anch’essi zero righe e contano comunque come un file. Questo copre alberi generati come target/ quando un verificatore reindirizza lì il proprio output (cargo clippy > target/review/clippy.log). L’esenzione si applica solo quando git esce con 0. Un repository mancante, un fallimento di git e un file tracciato mantengono l’addebito normale delle righe, incluso un file tracciato il cui nome corrisponde a un modello di ignore.

Profili

Imposta autonomy.profile per seminare più campi insieme (i campi espliciti vincono comunque):

Ispeziona con /limits

In una sessione, esegui /limits per stampare la pila di budget risolta, il denominatore effettivo della TUI per l’agente attivo, le sorgenti di configurazione e gli avvisi di doctor (per esempio quando agent.steps è più stretto del segmento di sessione). Usa /limits help per i nomi delle chiavi.

Che cosa mostra la TUI: durante un’esecuzione autonoma l’intestazione riporta turn current/max · total current/max · cont current/max. turn è il segmento di continuazione corrente e usa il tetto di ritmo effettivo per l’agente attivo — min(agent.steps, session.max_steps) quando l’agente è limitato, altrimenti il limite per segmento. total sopravvive alle auto-continuazioni. cont mostra ∞ quando un obiettivo attivo o la modalità Super-Long alza il tetto di continuazione ordinario.

Instradamento automatico: l’instradamento per parole chiave può passare la sessione a un agente specialista (Debug, Security, DevOps, …). Gli specialisti condividono la stessa policy di turni del modello illimitata per impostazione predefinita dell’agente Dev, salvo che tu imposti agent.<name>.steps. Disabilita l’instradamento con "routing": { "disable": true } se vuoi solo l’agente Dev.

Esecuzioni lunghe: usa /goal o Super-Long per lavoro di più ore: alzano i tetti di continuazione ordinari e usano il tetto cumulativo più grande (predefinito 20,000), con semantica di verifica e pausa documentata in Modalità ciclo. /goal scrive prima un contratto rivedibile (criteri di accettazione + piano di verifica) e si chiude in pausa se quel piano non può essere prodotto.

Quando un limite ferma un'esecuzione

Prima che un’esecuzione ordinaria raggiunga il tetto cumulativo di turni del modello, AX Code inietta un’istruzione di convergenza limitata (al massimo gli ultimi 50 turni, ridotta per i budget personalizzati piccoli). Dice al modello di fermare l’esplorazione ampia, finire o parcheggiare in sicurezza il lavoro in corso, eseguire una verifica mirata e riportare con verità il lavoro non finito. Non aggiunge budget e non aggira alcun tetto.

Quando si raggiunge un budget terminale, session.error include un code facoltativo leggibile dalla macchina, e l’evento di replay session.end registra lo stesso valore come stopCode. I motivi di fine grossolani esistenti restano invariati per compatibilità. I codici di limite correnti sono:

• MODEL_TURN_SEGMENT_LIMIT
• MODEL_TURN_TOTAL_LIMIT
• AGENT_MODEL_TURN_LIMIT
• AGGREGATE_TOOL_CALL_LIMIT
• FILE_CHANGE_LIMIT
• LINE_CHANGE_LIMIT

A un tetto di segmento, AX Code continua automaticamente finché resta il budget di continuazione configurato. Una volta esaurito quel budget, l’esecuzione si ferma e il messaggio dice che cosa è successo. Inviare un nuovo prompt come continue avvia una nuova esecuzione diretta dall’utente con una nuova contabilità di esecuzione; non estende retroattivamente l’esecuzione fermata. Usa /goal quando l’obiettivo deve restare esplicito e riprendibile fino al completamento, a un blocco o a un confine di budget di obiettivo o runtime. /goal non disabilita le protezioni di permesso, isolamento, raggio d’azione, stallo, token, tempo o turni cumulativi del modello.

Esempio: alza i budget per un lotto autonomo grande

{
  "autonomous": true,
  "autonomy": {
    "profile": "long",
    "budget": {
      "model_turns": { "per_segment": 500, "total": 20000 },
      "tool_calls": {
        "per_segment": 1000,
        "rate": { "count": 40, "window_seconds": 10 },
        "per_tool": { "bash": 80, "edit": 150 }
      },
      "changes": { "files_total": 100, "lines_total": 10000 }
    },
    "stall": {
      "tool_only_turns": 50,
      "tool_only_nudge": 20,
      "failed_mutation_attempts": 30,
      "max_consecutive_errors": 3
    }
  },
  "agent": {
    "debug": { "steps": 200 }
  }
}

Quando spegnere l'autonomo

• Imparare AX Code — vedi che cosa fa l’agente a ogni passo
• Operazioni sensibili — rivedi ogni modifica ai file prima che venga applicata
• Mettere a punto il comportamento dell’agente — capisci perché l’agente prende certe decisioni
• Codice non fidato — rivedi le chiamate di strumenti quando lavori con repository non familiari

Quando tenere acceso l'autonomo

• Compiti di routine — refactoring, correzioni di bug, migrazioni in cui ti fidi dell’agente
• Pipeline CI/CD — esecuzione headless in cui il compito è già vincolato dalla policy
• Uso dell’SDK — esecuzione programmatica dell’agente tramite createAgent()
• Compiti grandi — modifiche su più file in cui fermarsi a ogni permesso richiederebbe ore

Uso headless / CI

In modalità headless (ax-code run, ax-code serve, SDK), la modalità autonoma è essenziale: non c’è una TUI per mostrare i prompt. L’approvazione automatica lato server assicura che l’agente arrivi al completamento senza bloccarsi su prompt senza risposta.

# Headless one-shot with autonomous on (default)
ax-code run "Fix all TypeScript errors in src/"

# Explicit override
AX_CODE_AUTONOMOUS=true ax-code run "Migrate API routes"

ax-code run stampa per impostazione predefinita un output degli strumenti conciso: l’output dei comandi è ridotto alla coda, le modifiche mostrano un riepilogo del diff e le scritture dei todo mostrano un conteggio di progresso di una riga. Gli errori non vengono mai nascosti: sono resi con lo stesso tetto di coda dell’altro output. Passa --full per ripristinare l’output completo degli strumenti (diff completi, output dei comandi non troncato, elenchi todo completi) per l’audit.

Garanzie di sicurezza

Anche con la modalità autonoma attiva:

1. La sandbox applica ancora i confini — le scritture fuori dallo spazio di lavoro sono bloccate indipendentemente dalla modalità autonoma
2. L’escalation dell’isolamento chiede sempre — l’agente non può scavalcare in silenzio le restrizioni della sandbox
3. Le regole di negazione sono applicate — le regole di permesso esplicite "deny" bloccano ancora le chiamate di strumenti
4. Le scelte autonome sono registrate — i metadati dello strumento di domanda includono un registro strutturato autonomousDecisions, e l’output dello strumento include le risposte selezionate così l’agente può riportarle dopo
5. Evita la sovraingegnerizzazione — la continuazione autonoma ricorda all’agente di preferire la modifica più semplice di pratica comune e di evitare astrazioni senza 3 o più casi d’uso concreti
6. Le istantanee di sessione sono registrate — ogni chiamata di strumento è registrata per audit e replay
7. L’interruzione funziona sempre — premere Esc (interrupt) ferma subito l’agente