# Gestione dei sottoagenti (/it/docs/verdent-for-vscode/agents-rules/subagent-management)
> Comprendere e gestire i sottoagenti in Verdent
I sottoagenti sono agenti AI specializzati che operano con un proprio prompt di sistema personalizzato, una finestra di contesto separata e un ambiente di esecuzione isolato. Gestiscono attività specifiche delegate dall'agente principale senza inquinare il contesto della conversazione principale.
**Caratteristiche principali:**
* **Finestre di contesto isolate:** ogni sottoagente mantiene la propria finestra di contesto separata. Solo i risultati finali restituiti dai sottoagenti occupano spazio nel contesto dell'agente principale, non l'elaborazione intermedia.
* **Prompt di sistema personalizzati:** ogni sottoagente ha un prompt di sistema dedicato che ne definisce il comportamento, la personalità e l'approccio all'interpretazione delle attività.
* **Delega automatica delle attività:** l'agente principale invoca automaticamente i sottoagenti quando rileva i tipi di attività appropriati, in modo analogo alla selezione automatica degli strumenti.
* **Invocazione manuale:** puoi fare riferimento esplicito ai sottoagenti tramite @-menzioni (`@Verifier`, `@Explorer`, `@Code-reviewer`).
**Due categorie:**
* **Sottoagenti predefiniti:** integrati (Verifier, Explorer, Code-reviewer) — immediatamente disponibili, preconfigurati
* **Sottoagenti personalizzati:** creati dall'utente, memorizzati in `~/.verdent/subagents/` — adattati alle esigenze specifiche del progetto
***
## Comprendere i sottoagenti predefiniti [#comprendere-i-sottoagenti-predefiniti]
Verdent for VS Code include tre sottoagenti predefiniti integrati, già configurati, immediatamente disponibili e che non richiedono alcuna installazione o configurazione.
**Specializzazione:** controlli e convalide rapide del codice
**Capacità:**
* Convalida la logica del codice
* Verifica la correttezza sintattica
* Confronta l'implementazione con i requisiti
**Utilizzo:**
Fai riferimento durante le attività di scrittura del codice:
```
@Verifier check this authentication logic
```
**Ideale per:** convalida rapida senza il sovraccarico di una revisione completa del codice
**Specializzazione:** esplorazione e navigazione veloce della base di codice
**Capacità:**
* Trova file per pattern o nome
* Cerca nel codice parole chiave/funzioni
* Risponde a domande sull'architettura
* Identifica dove è implementata una funzionalità
**Utilizzo:**
Invocato automaticamente per domande sulla base di codice o su richiesta esplicita:
```
@Explorer find all API endpoints
```
**Ideale per:**
* Comprendere basi di codice non familiari
* Individuare implementazioni specifiche
* Analisi architetturale
**Prestazioni:** efficiente in termini di token, può eseguire più istanze in parallelo per ricerche complesse
**Specializzazione:** valutazione della qualità del codice
**Capacità:**
* Analizza in modo proattivo il codice nuovo e modificato alla ricerca di vulnerabilità di sicurezza
* Identifica problemi di manutenibilità
* Rileva problemi di prestazioni
**Utilizzo:**
Fai riferimento per i controlli di qualità:
```
@Code-reviewer review this authentication flow
```
**Ideale per:**
* Revisioni pre-commit
* Identificare problemi prima dell'integrazione
* Garantire gli standard di qualità del codice
***
### Invocazione automatica vs manuale [#invocazione-automatica-vs-manuale]
**Trigger di selezione automatica:**
L'agente principale seleziona automaticamente i sottoagenti in base al riconoscimento dei pattern delle attività:
**Sottoagente Explorer:**
* Domande sulla struttura della base di codice ("Qual è l'architettura?", "Dove è implementato X?")
* Richieste di ricerca di file ("Trova tutti i file che...", "Mostrami i componenti relativi a...")
* Query di navigazione del codice ("Come funziona l'autenticazione?", "Cosa chiama questa funzione?")
**Sottoagente Code-reviewer:**
* Richieste di revisione della sicurezza ("Rivedi le vulnerabilità di sicurezza", "Controlla i rischi di SQL injection")
* Prompt di valutazione della qualità del codice ("Analizza la qualità del codice", "Identifica i problemi di manutenibilità")
* Scenari di revisione pre-commit (implicitamente quando vengono presentate modifiche al codice)
**Sottoagente Verifier:**
* Richieste di convalida ("Verifica questa logica", "Controlla se questa implementazione è corretta")
* Controlli di sintassi e correttezza ("Questo codice funziona?", "Convalida il flusso di autenticazione")
**Specifica manuale:**
Puoi ignorare il routing automatico usando le @-menzioni:
```
@Explorer find all authentication-related files
@Code-reviewer review the security of login flow
@Verifier check validation logic in middleware
```
**Pulsante Add Subagent:**
Seleziona il pulsante **Add Subagent** nella casella di input per:
* Scegliere tra i sottoagenti disponibili (predefiniti e personalizzati)
* Delegare esplicitamente l'attività al sottoagente scelto
* Ignorare le decisioni di routing automatico
**Vantaggi della specifica manuale:**
* **Precisione:** garantisci che a gestire l'attività sia esattamente il sottoagente giusto
* **Override:** scegli un sottoagente specifico quando ne potrebbero essere applicabili più di uno
* **Test:** convalida esplicitamente il comportamento di un sottoagente personalizzato
* **Coerenza:** ripeti le attività con lo stesso sottoagente per ottenere risultati coerenti
I sottoagenti personalizzati possono essere invocati automaticamente in base alle linee guida "When to use" definite nella policy di invocazione del prompt di sistema del sottoagente. I dettagli sulla configurazione dei pattern di trigger sono attualmente in fase di sviluppo.
***
## Creare sottoagenti personalizzati [#creare-sottoagenti-personalizzati]
I sottoagenti personalizzati ti consentono di creare agenti specializzati adattati alle esigenze specifiche del progetto, alle competenze di dominio o ai flussi di lavoro del team.
### Metodi di creazione [#metodi-di-creazione]
**Consigliato per i principianti**
1. Seleziona **Settings** → **Subagents**
2. Scegli "Create new subagent"
3. Definisci nome, descrizione e prompt di sistema del sottoagente
4. Configura la policy di invocazione e le linee guida di utilizzo
5. Salva nella directory `~/.verdent/subagents/`
Questo metodo offre un'interfaccia guidata per creare sottoagenti con convalida e prompt utili.
**Consigliato per gli utenti avanzati**
1. Vai a `~/.verdent/subagents/`
2. Crea un file markdown (ad esempio `security-reviewer.md`)
3. Aggiungi il frontmatter YAML con `name` e `description`
4. Scrivi il prompt di sistema che definisce il comportamento
5. Specifica la policy di invocazione e le linee guida "When to use"
Questo metodo offre maggiore controllo ed è più veloce per chi ha familiarità con la struttura dei file.
Condividi i sottoagenti personalizzati tra i progetti memorizzandoli in \~/.verdent/subagents/. Saranno disponibili in tutti i workspace.
***
### Struttura del file [#struttura-del-file]
I file dei sottoagenti personalizzati usano il formato Markdown con frontmatter YAML:
```markdown
---
name: subagent-name
description: Brief description of specialization
---
# System Prompt
[Behavior definition, personality, interpretation style]
Invocation policy (strict): Only run if explicitly requested.
When to use:
- Specific scenario 1
- Specific scenario 2
When NOT to use:
- Avoid scenario 1
- Avoid scenario 2
```
**Frontmatter YAML (obbligatorio):**
* `name`: identificatore del sottoagente usato nelle @-menzioni
* `description`: descrizione in una riga dello scopo del sottoagente
**Sezione del prompt di sistema:**
Contenuto Markdown che definisce il comportamento del sottoagente:
* Personalità e tono
* Approccio all'interpretazione delle attività
* Preferenze sul formato di output
* Principi decisionali
**Policy di invocazione (obbligatoria):**
```
Invocation policy (strict|flexible): Policy description
```
* **strict:** invoca solo quando esplicitamente richiesto dall'utente
* **flexible:** consenti l'invocazione automatica in base ai pattern delle attività
**Linee guida di utilizzo:**
```
When to use the [name] agent:
- Bullet list of scenarios for invocation
When NOT to use:
- Bullet list of scenarios to avoid
```
***
### Esempi di sottoagenti personalizzati [#esempi-di-sottoagenti-personalizzati]
```markdown
---
name: api-documenter
description: Generates comprehensive API documentation from code
---
# System Prompt
You are an API documentation specialist.
Documentation approach:
- Extract endpoints, parameters, and responses from code
- Generate OpenAPI/Swagger specifications
- Include usage examples and error codes
- Document authentication requirements
Output format:
- Markdown tables for endpoints
- Code examples in multiple languages
- Authentication flow diagrams
Invocation policy (strict): Only run when explicitly requested.
When to use:
- User requests API documentation generation
- Need to document REST/GraphQL endpoints
- Creating developer guides
When NOT to use:
- Inline code comments
- User-facing documentation
```
**Caso d'uso:** genera automaticamente una documentazione API completa analizzando gli handler delle route, i controller e le definizioni degli schemi.
```markdown
---
name: migration-reviewer
description: Reviews database migrations for safety and correctness
---
# System Prompt
You are a database migration safety specialist.
Review checklist:
- Check for destructive operations (DROP, DELETE without WHERE)
- Verify reversible migrations (up/down compatibility)
- Identify potential data loss scenarios
- Validate index creation strategies
- Check for blocking operations on large tables
Risk assessment:
- Categorize migrations: low/medium/high risk
- Recommend staging environment testing for high-risk changes
- Suggest rollback procedures
Invocation policy (strict): Only run when explicitly requested.
When to use:
- User creates or modifies migration files
- Pre-deployment migration review
- Investigating migration failures
When NOT to use:
- Schema design from scratch
- Query optimization
```
**Caso d'uso:** previeni incidenti in produzione identificando operazioni rischiose sul database prima del rilascio.
```markdown
---
name: a11y-auditor
description: Audits frontend code for accessibility compliance
---
# System Prompt
You are an accessibility compliance specialist (WCAG 2.1 Level AA).
Audit criteria:
- Semantic HTML structure
- ARIA labels and roles
- Keyboard navigation support
- Color contrast ratios
- Screen reader compatibility
- Focus management
Report format:
- Issues categorized by severity (critical/major/minor)
- WCAG guideline references
- Code examples showing fixes
- Testing recommendations
Invocation policy (flexible): May auto-invoke for UI component reviews.
When to use:
- User creates/modifies UI components
- Pre-deployment accessibility checks
- Compliance audits
When NOT to use:
- Backend API code
- Build configuration files
```
**Caso d'uso:** assicurati che le applicazioni web soddisfino gli standard di accessibilità prima del rilascio.
***
### Casi d'uso comuni per i sottoagenti personalizzati [#casi-duso-comuni-per-i-sottoagenti-personalizzati]
**Competenze specifiche di dominio**
* **Calcoli finanziari:** sottoagente specializzato in conformità fiscale e normative finanziarie
* **Conformità HIPAA in ambito sanitario:** rivedi il codice per gli standard di gestione dei dati dei pazienti
* **Crittografia:** analizza le implementazioni di sicurezza rispetto alle best practice
Ideale per settori con requisiti di conoscenza specializzata e vincoli normativi.
**Flussi di lavoro specifici del team**
* **Applicazione dello stile del codice:** verifica il rispetto degli standard di codifica specifici del team oltre alle regole del linter
* **Coerenza della documentazione:** assicurati che i documenti seguano i modelli e il tono del team
* **Verifica delle dipendenze:** monitora l'uso di pacchetti di terze parti rispetto alle liste approvate
Applica le convenzioni del team e mantieni la coerenza nei progetti collaborativi.
**Specialisti dello stack tecnologico**
* **Ottimizzatore delle prestazioni React:** identifica re-render superflui e opportunità di memoizzazione
* **Ottimizzatore di query SQL:** analizza e migliora le prestazioni delle query sul database
* **Revisore della configurazione Docker:** convalida le best practice di containerizzazione
Competenze approfondite su framework, linguaggi o tecnologie infrastrutturali specifici.
**Garanzia di qualità**
* **Analizzatore della copertura dei test:** identifica i percorsi di codice non testati, suggerisci scenari di test
* **Revisore della gestione degli errori:** assicura una gestione completa delle eccezioni
* **Applicazione degli standard di logging:** verifica le pratiche di logging per il debug e il monitoraggio
Controlli di qualità automatizzati per mantenere l'affidabilità e la manutenibilità del codice.
**Conformità e sicurezza**
* **Verifica della conformità al GDPR:** rivedi la gestione dei dati rispetto ai requisiti sulla privacy
* **Scanner delle vulnerabilità di sicurezza:** rilevamento specializzato per problemi specifici del framework
* **Verifica della conformità delle licenze:** controlla le dipendenze per la compatibilità delle licenze
Assicura il rispetto dei requisiti legali, di sicurezza e di licenza prima del rilascio.
**Esigenze specifiche del progetto**
* **Modernizzatore di codice legacy:** identifica pattern obsoleti, suggerisci alternative moderne
* **Assistente alla migrazione:** guida gli aggiornamenti di versione di framework o linguaggi
* **Applicazione del budget di prestazioni:** monitora le dimensioni dei bundle e i tempi di caricamento rispetto alle soglie
Soluzioni personalizzate adattate alle sfide uniche del progetto e alla gestione del debito tecnico.
***
## Configurazione del comportamento dei sottoagenti (pattern AGENTS.md) [#configurazione-del-comportamento-dei-sottoagenti-pattern-agentsmd]
Sebbene AGENTS.md funga principalmente da file di regole del progetto (vedi [Sistemi di regole](/docs/verdent-for-vscode/agents-rules/rule-systems)), può anche definire il comportamento dei sottoagenti specifico del progetto.
### Principi di progettazione del prompt di sistema [#principi-di-progettazione-del-prompt-di-sistema]
**Sii specifico e direttivo:**
Definisci aspettative di comportamento precise anziché indicazioni generiche.
Sii specifico e direttivo nei prompt di sistema: "Fai il profiling prima di ottimizzare" è meglio di "Cerca di ottimizzare quando possibile".
**Buono:**
```markdown
Analysis approach:
- Profile before optimizing
- Focus on algorithmic improvements
- Provide before/after benchmarks
```
**Da evitare:**
```markdown
Try to optimize code when possible
```
**Definisci personalità e tono:**
Crea "personas" distinte ottimizzate per scopi specifici:
```markdown
You are a performance optimization specialist.
```
**Definisci i principi decisionali:**
Guida il modo in cui il sottoagente dovrebbe affrontare i compromessi:
```markdown
When suggesting optimizations:
1. Measure first, optimize second
2. Prioritize readability over micro-optimizations
3. Only suggest changes with >10% performance improvement
```
**Specifica il formato di output:**
Controlla come vengono presentati i risultati:
```markdown
Output format:
- Markdown tables for endpoints
- Code examples in multiple languages
- Authentication flow diagrams
```
***
### Configurazione della policy di invocazione [#configurazione-della-policy-di-invocazione]
**Policy strict:**
```markdown
Invocation policy (strict): Only run when explicitly requested.
```
Usala quando:
* Il sottoagente gestisce operazioni sensibili (revisioni di sicurezza, migrazioni del database)
* L'utente dovrebbe decidere consapevolmente quando invocarlo
* L'invocazione automatica potrebbe essere disruptiva
**Policy flexible:**
```markdown
Invocation policy (flexible): May auto-invoke based on task patterns.
```
Usala quando:
* Il sottoagente fornisce contesto utile senza creare disturbo
* L'invocazione automatica migliora l'efficienza del flusso di lavoro
* I pattern delle attività sono chiaramente identificabili
**Best practice per le linee guida di utilizzo:**
**Sezione "When to use":**
* Sii specifico riguardo agli scenari di trigger
* Includi prompt di esempio che dovrebbero invocare il sottoagente
* Descrivi le caratteristiche delle attività che corrispondono alla specializzazione del sottoagente
**Sezione "When NOT to use":**
* Elenca esplicitamente le esclusioni per prevenire invocazioni inappropriate
* Chiarisci i confini con i sottoagenti correlati
* Previeni l'ampliamento incontrollato dell'ambito
***
## Routing e dispatch delle attività [#routing-e-dispatch-delle-attività]
Il sistema multi-sottoagente di Verdent consente l'esecuzione parallela delle attività con routing e coordinamento automatici tra agenti specializzati.
### Componenti dell'architettura [#componenti-dellarchitettura]
**Agente principale (orchestratore):**
L'agente principale analizza le richieste dell'utente, scompone le attività complesse e delega il lavoro specializzato ai sottoagenti appropriati. Mantiene il contesto della conversazione e coordina i risultati dei sottoagenti.
**Pool di sottoagenti:**
Insieme dei sottoagenti disponibili (sia predefiniti che personalizzati) che possono essere invocati automaticamente o manualmente. Ciascuno opera in modo indipendente con un contesto isolato.
**Routing automatico delle attività:**
Quando l'agente principale rileva pattern di attività corrispondenti alle specializzazioni dei sottoagenti, distribuisce automaticamente il lavoro:
* Domande di esplorazione della base di codice → sottoagente Explorer
* Richieste di revisione della sicurezza → sottoagente Code-reviewer
* Controlli di convalida → sottoagente Verifier
**Esecuzione parallela:**
Più sottoagenti possono essere eseguiti contemporaneamente per operazioni complesse. Esempio: il sottoagente Explorer cerca nella base di codice mentre Code-reviewer analizza la sicurezza in parallelo, fornendo risultati più rapidi.
L'esecuzione parallela dei sottoagenti accelera le attività complesse: Explorer può cercare mentre Code-reviewer analizza contemporaneamente.
**Consolidamento dei risultati:**
Gli output dei sottoagenti vengono restituiti all'agente principale, che sintetizza i risultati e presenta risposte unificate all'utente.
Le informazioni dettagliate su pianificazione dell'esecuzione dei sottoagenti, priorità, limiti massimi di concorrenza, gestione degli errori e allocazione delle risorse sono attualmente in fase di sviluppo. Contatta il supporto per domande specifiche sull'architettura.
***
## Monitoraggio dei sottoagenti [#monitoraggio-dei-sottoagenti]
Tieni traccia dell'utilizzo e delle prestazioni dei sottoagenti tramite la Chat View, dove Verdent mostra le operazioni e i risultati dei sottoagenti.
### Metodi di monitoraggio [#metodi-di-monitoraggio]
**Indicatori nella Chat View:**
* Le invocazioni dei sottoagenti compaiono nella cronologia della conversazione
* Gli indicatori di avanzamento mostrano quando i sottoagenti sono in esecuzione
* I risultati identificano esplicitamente quale sottoagente ha fornito l'output
**Sezione degli output dei sottoagenti:**
Visualizzazione dedicata per:
* I risultati dell'esecuzione delle attività dei sottoagenti
* Gli indicatori di avanzamento per le attività parallele
* I riepiloghi consolidati al completamento delle attività
**Attribuzione delle risposte:**
Verdent attribuisce i risultati a specifici sottoagenti nelle risposte, rendendo chiaro quale agente ha eseguito quale analisi o ricerca.
### Visibilità e trasparenza [#visibilità-e-trasparenza]
**Trasparenza delle operazioni:**
Verdent mostra:
* Quale sottoagente è stato invocato
* Se l'invocazione è stata automatica o manuale
* Il motivo della delega dell'attività
* Lo stato di esecuzione del sottoagente
**Verifica della specifica manuale:**
Quando usi le @-menzioni, Verdent conferma che il sottoagente specificato sta gestendo l'attività, garantendo il rispetto delle tue preferenze di routing.
Le funzionalità di monitoraggio avanzate, tra cui log di esecuzione dettagliati, metriche di prestazione (tempo di esecuzione, utilizzo dei token), tracciamento storico delle invocazioni, impostazioni di visibilità dell'attività e dashboard di analisi dell'utilizzo, sono attualmente in fase di sviluppo.
***
## Vedi anche [#vedi-anche]
Configura il comportamento di Verdent tramite regole utente, regole di progetto e regole di piano
Riferimento completo degli strumenti e delle funzionalità disponibili