Sottoagenti: Delegare Compiti Specializzati
In questa pagina
Lezione aggiornata il 2 novembre 2026. I file degli agenti di esempio utilizzano ora le chiavi documentate da Vibe:
instructions(nonsystem_prompt),active_model(nonmodel), blocchi[tools.<tool>]per le approvazioni (la chiaveauto_approvenon esiste in un file agente) e nomi reali degli strumenti (edit, nonedit_file; nessuno strumentolist_dir). Promemoria dalla Lezione 3:safetyè un indicatore visivo, non un permesso. Fonte: Riferimento configurazione.
Il Principio di Delega
Nei progetti complessi, alcuni compiti sono indipendenti l’uno dall’altro: analizzare la sicurezza di un file mentre un altro processo genera test. Invece di gestire tutto sequenzialmente, Mistral Vibe ti permette di delegare i compiti ai sottoagenti. Un sottoagente è un agente che esegue in modo indipendente, completa la sua missione e restituisce un risultato testuale all’agente principale. Non può porre domande all’utente: deve essere completamente autonomo.
Questo vincolo è la chiave di tutto ciò che segue e merita dettagli. Un sottoagente esegue nel proprio contesto, senza accesso alla conversazione corrente: non sa nulla di ciò che hai spiegato all’agente principale cinque minuti fa. Non può usare ask_user_question e deve gestire l’ambiguità da solo. Restituisce un testo che l’agente principale integra poi nella sua risposta. Poiché è isolato dallo scambio, ha senso solo se progettato per un compito specifico e ben definito.
Configurare un Sottoagente
Per trasformare un agente in un sottoagente, aggiungi il campo agent_type = "subagent" al file .toml. Il resto della configurazione segue le regole usuali per gli agenti personalizzati.
# ~/.vibe/agents/test-generator.toml
display_name = "Generatore di Test"
description = "Genera test unitari per le funzioni fornite."
agent_type = "subagent"
safety = "neutral"
active_model = "codestral" # alias dichiarato in config.toml (Lezione 2)
instructions = """
Ricevi codice sorgente. Genera test unitari completi:
- Test per casi nominali
- Test per casi limite (null, undefined, stringhe vuote)
- Test per errori attesi
Framework: Usa il framework di test del progetto (Jest, Vitest, Pytest...).
Restituisci solo il codice di test, pronto per essere copiato.
"""
enabled_tools = [
"read_file",
"grep",
]
Nota l’assenza di ask_user_question negli strumenti: non è una dimenticanza. Un sottoagente non può chiedere chiarimenti e il prompt di sistema compensa questa impossibilità specificando in anticipo il framework di test da usare e il formato esatto della risposta.
Casi d’Uso Concreti
Il primo vantaggio è il lavoro parallelo. L’agente principale può assegnare più compiti simultaneamente a diversi sottoagenti, ognuno dei quali lavora autonomamente prima di restituire il proprio risultato.
Agente Principale
├── Sottoagente "test-generator" → genera test
├── Sottoagente "doc-writer" → genera documentazione
└── Sottoagente "security-checker" → analizza vulnerabilità
Il secondo vantaggio riguarda i compiti altamente specializzati. Alcuni richiedono un prompt di sistema radicalmente diverso da quello dell’agente principale; invece di sovraccaricare un unico agente con istruzioni contraddittorie, deleghi. L’ottimizzatore SQL qui sotto è un buon esempio: il suo prompt parla solo di indici, piani di esecuzione e query N+1, cosa che non avrebbe senso in un agente generalista.
# ~/.vibe/agents/sql-optimizer.toml
display_name = "Ottimizzatore SQL"
description = "Analizza e ottimizza le query SQL."
agent_type = "subagent"
safety = "safe"
active_model = "mistral-medium-3.5" # modello integrato in Vibe
instructions = """
Analizza le query SQL fornite:
1. Identifica i problemi di prestazioni (N+1, scansione completa, indice mancante)
2. Proponi query ottimizzate
3. Suggerisci indici da creare
Restituisci un report strutturato con prima/dopo per ogni query.
"""
enabled_tools = ["read_file", "grep"]
Il terzo vantaggio, meno ovvio, è l’isolamento della sicurezza. Un sottoagente con safety = "safe" non può modificare file, anche se l’agente principale esegue in modalità destructive: i permessi non si ereditano verso il basso. Puoi quindi lavorare in una modalità permissiva affidando le analisi a sottoagenti ristretti che non hanno modo di agire sul repository.
# Sottoagente che può SOLO leggere
agent_type = "subagent"
safety = "safe"
enabled_tools = ["read_file", "grep"]
[tools.read_file]
permission = "always"
[tools.grep]
permission = "always"
Vibe fornisce anche un sottoagente integrato explore, che utilizza automaticamente quando deve attraversare il tuo codebase per rispondere a una domanda. Opera in modalità sola lettura e restituisce un riepilogo di ciò che ha trovato: esattamente lo schema che replichi con i tuoi sottoagenti personalizzati.
Progettare un Buon Sottoagente
Tutto dipende dall’autonomia del prompt di sistema: deve contenere tutte le istruzioni necessarie affinché il sottoagente arrivi alla fine senza mai porre una domanda. Questo richiede di anticipare i casi in cui le cose vanno storte e scrivere esattamente cosa deve fare l’agente in quelle situazioni, come nell’esempio seguente.
instructions = """
Analizza TUTTI i file TypeScript nel progetto.
Se un file non viene trovato, passa al successivo.
Se il framework di test non è identificabile, usa Vitest come predefinito.
Restituisci sempre un risultato, anche se parziale.
"""
Due riflessi completano questo lavoro. Dai al sottoagente rigorosamente gli strumenti di cui ha bisogno: un sottoagente di analisi non ha bisogno di write_file — e specifica il formato di output atteso nel prompt di sistema. L’agente principale deve poter sfruttare il risultato senza ambiguità: sarà lui, non tu, a leggere per primo questo testo.
Regole Stabilite da Vibe
La documentazione di Vibe specifica diverse regole che vale la pena conoscere prima di progettare i tuoi sottoagenti:
- un sottoagente restituisce solo testo all’agente principale e non può porre domande all’utente;
- può usare solo gli strumenti integrati autorizzati dal suo file, mai strumenti MCP, connettori o plugin, e mai con permessi più ampi dell’agente genitore: i suoi blocchi
[tools.<tool>]possono limitarlo ulteriormente, non espanderlo; - la sua
descriptionè obbligatoria: indica all’agente quando usarlo; un file senza descrizione viene segnalato anziché caricato; - esegue sul suo
active_model, o sul modello della sessione se nessuno è impostato; - l’agente principale lo avvia tramite delega, usando lo strumento
task; non viene selezionato con--agent; - per impostazione predefinita, possono esistere ed eseguire simultaneamente fino a 32 sottoagenti (
max_subagents,max_concurrent_subagents), eenable_subagents = falseinconfig.tomlvieta qualsiasi delega.
Senza un sottoagente personalizzato, l’agente può comunque avviare un sottoagente generico dotato delle proprie istruzioni e strumenti.
Punti chiave
- Un sottoagente è un agente indipendente che non può interagire con l’utente
- Configuralo con
agent_type = "subagent"nel file.toml - I sottoagenti sono ideali per il lavoro parallelo e i compiti specializzati
- Offrono un isolamento naturale della sicurezza
- Le
instructionsdevono essere completamente autonome: nessuna domanda consentita - Specifica sempre un formato di output chiaro nel prompt