Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Sottoagenti: Delegare Compiti Specializzati

Lezione 5 di 14 Aggiornata il 2 novembre 2026 Avanzato
In questa pagina
  1. Il Principio di Delega
  2. Configurare un Sottoagente
  3. Casi d’Uso Concreti
  4. Progettare un Buon Sottoagente
  5. Regole Stabilite da Vibe
  6. Punti chiave

Lezione aggiornata il 2 novembre 2026. I file degli agenti di esempio utilizzano ora le chiavi documentate da Vibe: instructions (non system_prompt), active_model (non model), blocchi [tools.<tool>] per le approvazioni (la chiave auto_approve non esiste in un file agente) e nomi reali degli strumenti (edit, non edit_file; nessuno strumento list_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), e enable_subagents = false in config.toml vieta 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 instructions devono essere completamente autonome: nessuna domanda consentita
  • Specifica sempre un formato di output chiaro nel prompt