Gestion des sous-agents

Les sous-agents sont des agents IA spécialisés qui fonctionnent avec leur propre prompt système personnalisé, une fenêtre de contexte distincte et un environnement d'exécution isolé. Ils traitent des tâches spécifiques déléguées par l'agent principal sans polluer le contexte de la conversation principale.

Caractéristiques principales :

• Fenêtres de contexte isolées : Chaque sous-agent conserve sa propre fenêtre de contexte distincte. Seuls les résultats finaux renvoyés par les sous-agents occupent de l'espace dans le contexte de l'agent principal, pas le traitement intermédiaire.
• Prompts système personnalisés : Chaque sous-agent dispose d'un prompt système dédié qui définit son comportement, sa personnalité et son approche d'interprétation des tâches.
• Délégation automatique des tâches : L'agent principal invoque automatiquement les sous-agents lorsque des types de tâches appropriés sont détectés, de manière similaire à la sélection automatique d'outils.
• Invocation manuelle : Les utilisateurs peuvent référencer explicitement les sous-agents à l'aide de mentions @ (@Verifier, @Explorer, @Code-reviewer).

Deux catégories :

• Sous-agents par défaut : Intégrés (Verifier, Explorer, Code-reviewer) - immédiatement disponibles, préconfigurés
• Sous-agents personnalisés : Créés par l'utilisateur, stockés dans ~/.verdent/subagents/ - adaptés aux besoins spécifiques du projet

Comprendre les sous-agents par défaut

Verdent for VS Code inclut trois sous-agents par défaut intégrés qui sont préconfigurés, immédiatement disponibles et ne nécessitent aucune installation ni configuration.

@Verifier check this authentication logic

@Explorer find all API endpoints

@Code-reviewer review this authentication flow

Invocation automatique et manuelle

Déclencheurs de sélection automatique :

L'agent principal sélectionne automatiquement les sous-agents en fonction de la reconnaissance des motifs de tâche :

Sous-agent Explorer :

• Questions sur la structure de la base de code (« Quelle est l'architecture ? », « Où X est-il implémenté ? »)
• Demandes de recherche de fichiers (« Trouve tous les fichiers qui... », « Montre-moi les composants liés à... »)
• Requêtes de navigation dans le code (« Comment fonctionne l'authentification ? », « Qui appelle cette fonction ? »)

Sous-agent Code-reviewer :

• Demandes de revue de sécurité (« Vérifie les vulnérabilités de sécurité », « Vérifie les risques d'injection SQL »)
• Prompts d'évaluation de la qualité du code (« Analyse la qualité du code », « Identifie les problèmes de maintenabilité »)
• Scénarios de revue avant commit (implicitement lorsque des modifications de code sont présentées)

Sous-agent Verifier :

• Demandes de validation (« Vérifie cette logique », « Vérifie si cette implémentation est correcte »)
• Vérifications de syntaxe et d'exactitude (« Ce code fonctionne-t-il ? », « Valide le flux d'authentification »)

Spécification manuelle :

Les utilisateurs peuvent remplacer le routage automatique à l'aide de mentions @ :

@Explorer find all authentication-related files
@Code-reviewer review the security of login flow
@Verifier check validation logic in middleware

Bouton Ajouter un sous-agent : Sélectionnez le bouton Ajouter un sous-agent dans la zone de saisie pour :

• Choisir parmi les sous-agents disponibles (par défaut et personnalisés)
• Déléguer explicitement une tâche au sous-agent choisi
• Remplacer les décisions de routage automatique

Avantages de la spécification manuelle :

• Précision : S'assurer que le sous-agent exact traite la tâche
• Remplacement : Choisir un sous-agent spécifique lorsque plusieurs pourraient s'appliquer
• Test : Valider explicitement le comportement d'un sous-agent personnalisé
• Cohérence : Répéter des tâches avec le même sous-agent pour des résultats cohérents

Créer des sous-agents personnalisés

Les sous-agents personnalisés vous permettent de créer des agents spécialisés adaptés aux besoins spécifiques de votre projet, à votre expertise métier ou aux flux de travail de votre équipe.

Méthodes de création

Structure de fichier

Les fichiers de sous-agents personnalisés utilisent le format Markdown avec un en-tête 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

En-tête YAML (obligatoire) :

• name : identifiant du sous-agent utilisé dans les mentions @
• description : description en une ligne de l'objectif du sous-agent

Section prompt système : Contenu markdown définissant le comportement du sous-agent :

• Personnalité et ton
• Approche d'interprétation des tâches
• Préférences de format de sortie
• Principes de prise de décision

Politique d'invocation (obligatoire) :

Invocation policy (strict|flexible): Policy description

• stricte : invoquer uniquement lorsque l'utilisateur le demande explicitement
• flexible : autoriser l'invocation automatique en fonction des motifs de tâche

Directives d'utilisation :

When to use the [name] agent:
- Bullet list of scenarios for invocation

When NOT to use:
- Bullet list of scenarios to avoid

Exemples de sous-agents personnalisés

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

Cas d'usage courants pour les sous-agents personnalisés

Configuration du comportement des sous-agents (motif AGENTS.md)

Bien que AGENTS.md serve principalement de fichier de règles de projet (voir Systèmes de règles), il peut aussi définir un comportement de sous-agent spécifique au projet.

Principes de conception du prompt système

Soyez précis et directif : Définissez des attentes de comportement exactes plutôt que des consignes générales.

Bon exemple :

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

À éviter :

Try to optimize code when possible

Établir une personnalité et un ton : Créez des « personas » distincts optimisés pour des objectifs spécifiques :

You are a performance optimization specialist.

Définir les principes de prise de décision : Guidez la manière dont le sous-agent doit aborder les compromis :

When suggesting optimizations:
1. Measure first, optimize second
2. Prioritize readability over micro-optimizations
3. Only suggest changes with >10% performance improvement

Préciser le format de sortie : Contrôlez la manière dont les résultats sont présentés :

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

Configuration de la politique d'invocation

Politique stricte :

Invocation policy (strict): Only run when explicitly requested.

À utiliser lorsque :

• Le sous-agent traite des opérations sensibles (revues de sécurité, migrations de base de données)
• L'utilisateur doit décider consciemment quand l'invoquer
• L'invocation automatique pourrait être perturbatrice

Politique flexible :

Invocation policy (flexible): May auto-invoke based on task patterns.

À utiliser lorsque :

• Le sous-agent fournit un contexte utile sans perturbation
• L'invocation automatique améliore l'efficacité du flux de travail
• Les motifs de tâche sont clairement identifiables

Bonnes pratiques pour les directives d'utilisation :

Section « Quand l'utiliser » :

• Soyez précis sur les scénarios de déclenchement
• Incluez des exemples de prompts qui devraient invoquer le sous-agent
• Décrivez les caractéristiques de tâche correspondant à la spécialisation du sous-agent

Section « Quand ne pas l'utiliser » :

• Listez explicitement les exclusions pour éviter une invocation inappropriée
• Clarifiez les limites avec les sous-agents apparentés
• Empêchez l'élargissement non maîtrisé du périmètre

Routage et répartition des tâches

Le système multi-sous-agents de Verdent permet l'exécution parallèle de tâches avec routage et coordination automatiques entre agents spécialisés.

Composants de l'architecture

Agent principal (orchestrateur) : L'agent principal analyse les demandes de l'utilisateur, décompose les tâches complexes et délègue le travail spécialisé aux sous-agents appropriés. Il maintient le contexte de la conversation et coordonne les résultats des sous-agents.

Pool de sous-agents : Ensemble de sous-agents disponibles (par défaut et personnalisés) pouvant être invoqués automatiquement ou manuellement. Chacun fonctionne de manière indépendante avec un contexte isolé.

Routage automatique des tâches : Lorsque l'agent principal détecte des motifs de tâche correspondant aux spécialisations des sous-agents, il répartit automatiquement le travail :

• Questions d'exploration de la base de code → sous-agent Explorer
• Demandes de revue de sécurité → sous-agent Code-reviewer
• Vérifications de validation → sous-agent Verifier

Exécution parallèle : Plusieurs sous-agents peuvent s'exécuter simultanément pour des opérations complexes. Exemple : le sous-agent Explorer recherche dans la base de code tandis que Code-reviewer analyse la sécurité en parallèle, ce qui accélère les résultats.

Consolidation des résultats : Les sorties des sous-agents sont renvoyées à l'agent principal, qui synthétise les résultats et présente des réponses unifiées à l'utilisateur.

Suivi des sous-agents

Suivez l'utilisation et la performance des sous-agents via la vue de discussion où Verdent affiche les opérations et les résultats des sous-agents.

Méthodes de suivi

Indicateurs dans la vue de discussion :

• Les invocations de sous-agents apparaissent dans l'historique de la conversation
• Des indicateurs de progression s'affichent pendant l'exécution des sous-agents
• Les résultats identifient explicitement quel sous-agent a fourni la sortie

Section des sorties des sous-agents : Affichage dédié pour :

• Les résultats de l'exécution des tâches des sous-agents
• Les indicateurs de progression pour les tâches parallèles
• Les résumés consolidés une fois les tâches terminées

Attribution des réponses : Verdent attribue les résultats à des sous-agents spécifiques dans les réponses, ce qui permet de savoir clairement quel agent a effectué quelle analyse ou recherche.

Visibilité et transparence

Transparence des opérations : Verdent indique :

• Quel sous-agent a été invoqué
• Si l'invocation était automatique ou manuelle
• La raison de la délégation de la tâche
• Le statut d'exécution du sous-agent

Vérification de la spécification manuelle : Lorsque vous utilisez des mentions @, Verdent confirme que le sous-agent spécifié traite la tâche, garantissant ainsi le respect de vos préférences de routage.

Voir aussi