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

Instradamento Auto-Route

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

Auto-route controlla due comportamenti di instradamento indipendenti in ax-code:

Instradamento per parole chiave — attivo per impostazione predefinita. Cambia agente quando un messaggio corrisponde alle parole chiave o ai motivi di uno specialista. Scatta in meno di 1ms e non richiede una chiamata LLM. Viene saltato quando l’instradamento è disattivato in modo esplicito, quando l’utente nomina un agente in modo esplicito, oppure quando il messaggio è una continuazione sintetica che conserva l’agente corrente.
Instradamento per complessità — facoltativo, attivato dall’interruttore di auto-route. Una chiamata LLM leggera classifica ogni messaggio come complessità low, medium o high. I messaggi di complessità low vengono serviti in automatico dal small_model configurato in modo esplicito, riducendo la latenza delle domande semplici.

Per impostazione predefinita, auto-route è spento: l’instradamento per complessità è disattivato. L’instradamento per parole chiave è separato da questo interruttore e resta attivo per impostazione predefinita, salvo disattivazione da configurazione o aggiramento per una scelta esplicita di agente.

Avvio rapido

Attiva o disattiva dalla TUI:

Digita /smart-llm nel prompt, oppure
Premi Ctrl+P e cerca “auto-route”, oppure
Fai clic sull’indicatore Auto-route On/Off nella barra di stato

La barra di stato mostra lo stato corrente:

Auto-route On (testo viola) — l’instradamento per complessità è attivo
Auto-route Off (testo bianco) — instradamento per complessità disattivato (predefinito)

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

Come funziona

Fonte di verità

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

packages/ax-code/src/agent/router.ts per le regole di instradamento per parole chiave e classifyComplexity().
packages/ax-code/src/session/prompt.ts per quando l’instradamento per parole chiave viene saltato e quando gira la classificazione di complessità.
packages/ax-code/src/server/routes/smart-llm.ts per il comportamento predefinito, di ambiente, di configurazione e di persistenza.
packages/ax-code/src/config/schema.ts per i campi di configurazione dell’instradamento e le note di deprecazione.
packages/ax-code/src/cli/tui/app.tsx per i nomi dei comandi slash, gli alias, le etichette e le azioni della barra di stato.
packages/ax-code/test/agent/router.test.ts e i test di sincronizzazione della TUI per il comportamento di attivazione atteso.

Evita di descrivere l’instradamento per parole chiave e l’instradamento di complessità sul modello veloce come un’unica funzione. Sono separati di proposito.

Instradamento per parole chiave (attivo per impostazione predefinita, <1ms)

I messaggi dell’utente vengono confrontati con motivi di parole chiave e di espressioni regolari per ogni agente specialista (security, architect, debug, perf, devops, test). Se una corrispondenza raggiunge una confidenza ≥ 0.4, l’agente può cambiare subito: non viene fatta alcuna chiamata LLM. Questo percorso è indipendente dall’interruttore di auto-route, ma viene saltato quando l’instradamento è disattivato, quando l’utente nomina un agente in modo esplicito, oppure quando il turno corrente conserva un agente esistente per una continuazione sintetica.

Instradamento per complessità (solo auto-route, ~200-500ms)

Quando auto-route è attivo, ogni messaggio viene inviato a un modello veloce ed economico tramite classifyComplexity(). Questa chiamata LLM restituisce una stima di complessità (low / medium / high):

I messaggi di complessità low usano in automatico il small_model configurato in modo esplicito
I messaggi medium e high usano il modello predefinito come di consueto
Saltato se small_model è assente o non disponibile
Timeout di 1.5 secondi: ripiego silenzioso se l’LLM è lento o non disponibile
Tutti gli errori vengono catturati in silenzio: non bloccano mai l’utente

L’instradamento per complessità è indipendente dall’instradamento degli agenti. Non classifica quale agente specialista usare: quello è gestito interamente dall’instradamento per parole chiave.

A che cosa serve Auto-Route

Scenario	Senza Auto-Route	Con Auto-Route
“che cosa fa questa variabile?”	Si usa il modello completo	complessità `low` → modello veloce
“elenca tutte le esportazioni di questo file”	Si usa il modello completo	complessità `low` → modello veloce
“cerca le vulnerabilità”	Le parole chiave instradano verso security	Uguale: l’instradamento per parole chiave scatta sempre
“refactoring del modulo di autenticazione su 8 file”	Modello predefinito	complessità `high` → modello predefinito
“questa funzione è lenta”	Nessuna corrispondenza di parole chiave, nessun instradamento	`low`/`medium` → livello di modello corretto

L’instradamento per parole chiave gestisce la scelta dell’agente specialista per le parole chiave tecniche. L’instradamento per complessità seleziona il livello di modello appropriato in base a quanto ragionamento serve alla risposta.

Svantaggi e considerazioni

Latenza

L’instradamento per complessità aggiunge 200-500ms ai messaggi che innescano la chiamata di classificazione. L’instradamento per parole chiave (sempre attivo) non ne risente: risponde in <1ms in ogni caso.

Richiede un modello piccolo

L’instradamento per complessità richiede una configurazione esplicita di small_model. AX Code non deduce un aiutante dai nomi dei modelli e non sposta un pin non disponibile su un altro provider. Senza un aiutante utilizzabile, la classificazione viene saltata e il primario selezionato viene conservato. Vedi Recupero del modello.

Utilizzo dei token

Ogni chiamata di classificazione usa circa 100-200 token di input e 10-20 token di output: trascurabile rispetto alla chiamata LLM principale che segue.

Non sostituisce la selezione esplicita

Auto-route migliora la selezione automatica del livello di modello, ma non può instradare verso agenti specialisti basandosi solo sul linguaggio naturale. Per i compiti critici in cui conta lo specialista giusto, selezionare l’agente in modo esplicito dal selettore o con la menzione @agent è più affidabile.

Configurazione

Interruttore dalla TUI

Usa /smart-llm o la palette dei comandi (Ctrl+P → “Turn auto-route on/off”). La modifica ha effetto subito e viene salvata nel ax-code.json del progetto.

File di configurazione

{
  "routing": {
    "llm": true
  }
}

Variabile di ambiente

AX_CODE_SMART_LLM=true ax-code

La variabile di ambiente ha la precedenza sull’impostazione del file di configurazione.

Auto-Route e altre impostazioni

Impostazione	Interazione
Modalità autonoma	Auto-route funziona in modo indipendente. L’instradamento degli agenti e la classificazione di complessità avvengono prima dei controlli di autorizzazione.
Modalità sandbox	Nessuna interazione. Auto-route influisce solo su quale agente e quale livello di modello vengono selezionati, non su che cosa può fare l’agente.
Selezione del modello	I messaggi di complessità `low` usano il `small_model` configurato in modo esplicito quando auto-route è acceso e nessun modello è fissato in modo esplicito.
Modalità di esecuzione	Il collocamento ibrido (`modes.default: "hybrid"`) è separato: sceglie locale o cloud. Vedi Modalità di esecuzione.

Quando attivare Auto-Route

Attivalo se:

Vuoi che le domande semplici vadano in automatico a un modello più economico e più veloce
Vuoi ridurre il costo in token sugli scambi a bassa complessità
Lavori con un provider che ha un modello piccolo o flash affidabile

Tienilo disattivato se:

Preferisci latenza aggiunta pari a zero su ogni messaggio
Lavori offline o con una rete inaffidabile
Vuoi ridurre al minimo l’uso dei token
Fissi sempre un modello in modo esplicito