Gestión de subagentes

Los subagentes son agentes de IA especializados que operan con su propio prompt de sistema personalizado, una ventana de contexto separada y un entorno de ejecución aislado. Se encargan de tareas específicas delegadas por el agente principal sin contaminar el contexto de la conversación principal.

Características clave:

• Ventanas de contexto aisladas: Cada subagente mantiene su propia ventana de contexto separada. Solo los resultados finales que devuelven los subagentes consumen espacio en el contexto del agente principal, no el procesamiento intermedio.
• Prompts de sistema personalizados: Cada subagente tiene un prompt de sistema dedicado que define su comportamiento, su personalidad y su forma de interpretar las tareas.
• Delegación automática de tareas: El agente principal invoca automáticamente a los subagentes cuando detecta los tipos de tarea apropiados, de forma similar a la selección automática de herramientas.
• Invocación manual: Puedes referenciar explícitamente a los subagentes mediante menciones con @ (@Verifier, @Explorer, @Code-reviewer).

Dos categorías:

• Subagentes predeterminados: Integrados (Verifier, Explorer, Code-reviewer): disponibles de inmediato y preconfigurados
• Subagentes personalizados: Creados por ti, almacenados en ~/.verdent/subagents/, adaptados a las necesidades específicas del proyecto

Comprender los subagentes predeterminados

Verdent for VS Code incluye tres subagentes predeterminados integrados que están preconfigurados, disponibles de inmediato y no requieren configuración ni ajustes.

@Verifier check this authentication logic

@Explorer find all API endpoints

@Code-reviewer review this authentication flow

Invocación automática frente a manual

Desencadenantes de selección automática:

El agente principal selecciona automáticamente los subagentes según el reconocimiento de patrones de la tarea:

Subagente Explorer:

• Preguntas sobre la estructura de la base de código ("¿Cuál es la arquitectura?", "¿Dónde está implementado X?")
• Solicitudes de búsqueda de archivos ("Encuentra todos los archivos que...", "Muéstrame los componentes relacionados con...")
• Consultas de navegación por el código ("¿Cómo funciona la autenticación?", "¿Qué llama a esta función?")

Subagente Code-reviewer:

• Solicitudes de revisión de seguridad ("Revisa las vulnerabilidades de seguridad", "Comprueba los riesgos de inyección SQL")
• Prompts de evaluación de la calidad del código ("Analiza la calidad del código", "Identifica problemas de mantenibilidad")
• Escenarios de revisión previa a la confirmación (de forma implícita cuando se presentan cambios de código)

Subagente Verifier:

• Solicitudes de validación ("Verifica esta lógica", "Comprueba si esta implementación es correcta")
• Comprobaciones de sintaxis y corrección ("¿Funciona este código?", "Valida el flujo de autenticación")

Especificación manual:

Puedes anular el enrutamiento automático mediante menciones con @:

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

Botón Add Subagent: Selecciona el botón Add Subagent en el cuadro de entrada para:

• Elegir entre los subagentes disponibles (predeterminados y personalizados)
• Delegar explícitamente la tarea al subagente elegido
• Anular las decisiones de enrutamiento automático

Ventajas de la especificación manual:

• Precisión: Garantiza que el subagente exacto se encargue de la tarea
• Anulación: Elige un subagente específico cuando podrían aplicarse varios
• Pruebas: Valida explícitamente el comportamiento de un subagente personalizado
• Consistencia: Repite tareas con el mismo subagente para obtener resultados coherentes

Crear subagentes personalizados

Los subagentes personalizados te permiten crear agentes especializados adaptados a las necesidades específicas de tu proyecto, tu experiencia en un dominio o los flujos de trabajo de tu equipo.

Métodos de creación

Estructura de archivos

Los archivos de subagentes personalizados usan formato Markdown con frontmatter de 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 de YAML (obligatorio):

• name: Identificador del subagente que se usa en las menciones con @
• description: Descripción de una línea del propósito del subagente

Sección del prompt de sistema: Contenido Markdown que define el comportamiento del subagente:

• Personalidad y tono
• Forma de interpretar las tareas
• Preferencias de formato de salida
• Principios para la toma de decisiones

Política de invocación (obligatoria):

Invocation policy (strict|flexible): Policy description

• strict: Invocar solo cuando el usuario lo solicite explícitamente
• flexible: Permitir la invocación automática según los patrones de la tarea

Pautas de uso:

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

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

Ejemplos de subagentes personalizados

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

Casos de uso comunes de los subagentes personalizados

Configuración del comportamiento de los subagentes (patrón AGENTS.md)

Aunque AGENTS.md sirve principalmente como archivo de reglas del proyecto (consulta Sistemas de reglas), también puede definir el comportamiento de los subagentes específico del proyecto.

Principios de diseño del prompt de sistema

Sé específico y directivo: Define expectativas de comportamiento exactas en lugar de orientación general.

Bien:

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

Evita:

Try to optimize code when possible

Establece personalidad y tono: Crea "personas" distintas optimizadas para propósitos específicos:

You are a performance optimization specialist.

Define principios para la toma de decisiones: Orienta cómo debe abordar el subagente las concesiones:

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

Especifica el formato de salida: Controla cómo se presentan los resultados:

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

Configuración de la política de invocación

Política estricta:

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

Úsala cuando:

• El subagente maneja operaciones sensibles (revisiones de seguridad, migraciones de base de datos)
• El usuario debe decidir conscientemente cuándo invocarlo
• La invocación automática podría resultar disruptiva

Política flexible:

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

Úsala cuando:

• El subagente aporta contexto útil sin causar disrupción
• La invocación automática mejora la eficiencia del flujo de trabajo
• Los patrones de la tarea son claramente identificables

Mejores prácticas para las pautas de uso:

Sección "Cuándo usarlo":

• Sé específico sobre los escenarios desencadenantes
• Incluye prompts de ejemplo que deberían invocar al subagente
• Describe las características de la tarea que coinciden con la especialización del subagente

Sección "Cuándo NO usarlo":

• Enumera explícitamente las exclusiones para evitar invocaciones inapropiadas
• Aclara los límites con subagentes relacionados
• Evita la expansión del alcance

Enrutamiento y despacho de tareas

El sistema multisubagente de Verdent permite la ejecución de tareas en paralelo con enrutamiento automático y coordinación entre agentes especializados.

Componentes de la arquitectura

Agente principal (orquestador): El agente principal analiza las solicitudes del usuario, descompone las tareas complejas y delega el trabajo especializado a los subagentes apropiados. Mantiene el contexto de la conversación y coordina los resultados de los subagentes.

Grupo de subagentes: Conjunto de subagentes disponibles (tanto predeterminados como personalizados) que pueden invocarse de forma automática o manual. Cada uno opera de forma independiente con un contexto aislado.

Enrutamiento automático de tareas: Cuando el agente principal detecta patrones de tarea que coinciden con las especializaciones de los subagentes, despacha el trabajo automáticamente:

• Preguntas de exploración de la base de código → subagente Explorer
• Solicitudes de revisión de seguridad → subagente Code-reviewer
• Comprobaciones de validación → subagente Verifier

Ejecución en paralelo: Varios subagentes pueden ejecutarse de forma concurrente en operaciones complejas. Ejemplo: el subagente Explorer busca en la base de código mientras el Code-reviewer analiza la seguridad simultáneamente, entregando resultados más rápido.

Consolidación de resultados: Las salidas de los subagentes se devuelven al agente principal, que sintetiza los resultados y presenta respuestas unificadas al usuario.

Supervisión de subagentes

Realiza un seguimiento del uso y el rendimiento de los subagentes a través de la vista de chat, donde Verdent muestra las operaciones y los resultados de los subagentes.

Métodos de supervisión

Indicadores en la vista de chat:

• Las invocaciones de subagentes aparecen en el historial de la conversación
• Los indicadores de progreso muestran cuándo se están ejecutando los subagentes
• Los resultados identifican explícitamente qué subagente produjo la salida

Sección de salidas de subagentes: Pantalla dedicada para:

• Resultados de la ejecución de tareas de los subagentes
• Indicadores de progreso de las tareas en paralelo
• Resúmenes consolidados cuando las tareas se completan

Atribución de respuestas: Verdent atribuye los hallazgos a subagentes específicos en las respuestas, dejando claro qué agente realizó cada análisis o búsqueda.

Visibilidad y transparencia

Transparencia de operaciones: Verdent muestra:

• Qué subagente se invocó
• Si la invocación fue automática o manual
• El motivo de la delegación de la tarea
• El estado de ejecución del subagente

Verificación de la especificación manual: Cuando usas menciones con @, Verdent confirma que el subagente especificado se está encargando de la tarea, garantizando que se respeten tus preferencias de enrutamiento.

Consulta también