Gestione dei sottoagenti

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

Verdent for VS Code include tre sottoagenti predefiniti integrati, già configurati, immediatamente disponibili e che non richiedono alcuna installazione o configurazione.

@Verifier check this authentication logic

@Explorer find all API endpoints

@Code-reviewer review this authentication flow

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

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

Struttura del file

I file dei sottoagenti personalizzati usano il formato Markdown con frontmatter YAML:

---
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

---
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

---
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

---
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

Casi d'uso comuni per i sottoagenti personalizzati

Configurazione del comportamento dei sottoagenti (pattern AGENTS.md)

Sebbene AGENTS.md funga principalmente da file di regole del progetto (vedi Sistemi di regole), può anche definire il comportamento dei sottoagenti specifico del progetto.

Principi di progettazione del prompt di sistema

Sii specifico e direttivo: Definisci aspettative di comportamento precise anziché indicazioni generiche.

Buono:

Analysis approach:
- Profile before optimizing
- Focus on algorithmic improvements
- Provide before/after benchmarks

Da evitare:

Try to optimize code when possible

Definisci personalità e tono: Crea "personas" distinte ottimizzate per scopi specifici:

You are a performance optimization specialist.

Definisci i principi decisionali: Guida il modo in cui il sottoagente dovrebbe affrontare i compromessi:

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:

Output format:
- Markdown tables for endpoints
- Code examples in multiple languages
- Authentication flow diagrams

Configurazione della policy di invocazione

Policy strict:

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:

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à

Il sistema multi-sottoagente di Verdent consente l'esecuzione parallela delle attività con routing e coordinamento automatici tra agenti specializzati.

Componenti dell'architettura

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.

Consolidamento dei risultati: Gli output dei sottoagenti vengono restituiti all'agente principale, che sintetizza i risultati e presenta risposte unificate all'utente.

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

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

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.

Vedi anche