Gerenciamento de subagentes

Subagentes são agentes de IA especializados que operam com seu próprio system prompt personalizado, janela de contexto separada e ambiente de execução isolado. Eles lidam com tarefas específicas delegadas pelo agente principal sem poluir o contexto da conversa principal.

Características principais:

• Janelas de contexto isoladas: cada subagente mantém sua própria janela de contexto separada. Apenas os resultados finais retornados pelos subagentes consomem espaço no contexto do agente principal, e não o processamento intermediário.
• System prompts personalizados: cada subagente tem um system prompt dedicado que define seu comportamento, personalidade e abordagem de interpretação de tarefas.
• Delegação automática de tarefas: o agente principal invoca automaticamente os subagentes quando tipos de tarefa apropriados são detectados, de forma semelhante à seleção automática de ferramentas.
• Invocação manual: os usuários podem referenciar subagentes explicitamente usando @-menções (@Verifier, @Explorer, @Code-reviewer).

Duas categorias:

• Subagentes padrão: integrados (Verifier, Explorer, Code-reviewer) — disponíveis imediatamente, pré-configurados
• Subagentes personalizados: criados pelo usuário, armazenados em ~/.verdent/subagents/ — adaptados às necessidades específicas do projeto

Entendendo os subagentes padrão

O Verdent for VS Code inclui três subagentes padrão integrados que já vêm pré-configurados, disponíveis imediatamente e não exigem nenhuma configuração.

@Verifier check this authentication logic

@Explorer find all API endpoints

@Code-reviewer review this authentication flow

Invocação automática vs. manual

Gatilhos de seleção automática:

O agente principal seleciona automaticamente os subagentes com base no reconhecimento de padrões de tarefa:

Subagente Explorer:

• Perguntas sobre a estrutura da base de código ("Qual é a arquitetura?", "Onde X está implementado?")
• Solicitações de busca de arquivos ("Encontre todos os arquivos que...", "Mostre componentes relacionados a...")
• Consultas de navegação de código ("Como funciona a autenticação?", "O que chama esta função?")

Subagente Code-reviewer:

• Solicitações de revisão de segurança ("Revise as vulnerabilidades de segurança", "Verifique riscos de injeção de SQL")
• Prompts de avaliação de qualidade de código ("Analise a qualidade do código", "Identifique problemas de manutenibilidade")
• Cenários de revisão pré-commit (implicitamente, quando alterações de código são apresentadas)

Subagente Verifier:

• Solicitações de validação ("Verifique esta lógica", "Confira se esta implementação está correta")
• Verificações de sintaxe e correção ("Este código funciona?", "Valide o fluxo de autenticação")

Especificação manual:

Os usuários podem sobrepor o roteamento automático usando @-menções:

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

Botão Add Subagent: Clique no botão Add Subagent na caixa de entrada para:

• Selecionar entre os subagentes disponíveis (padrão e personalizados)
• Delegar explicitamente a tarefa ao subagente escolhido
• Sobrepor as decisões de roteamento automático

Benefícios da especificação manual:

• Precisão: garantir que o subagente exato lide com a tarefa
• Sobreposição: escolher um subagente específico quando vários poderiam se aplicar
• Testes: validar explicitamente o comportamento de um subagente personalizado
• Consistência: repetir tarefas com o mesmo subagente para obter resultados consistentes

Criando subagentes personalizados

Os subagentes personalizados permitem criar agentes especializados adaptados às necessidades específicas do seu projeto, à expertise de domínio ou aos fluxos de trabalho da sua equipe.

Métodos de criação

Estrutura do arquivo

Os arquivos de subagentes personalizados usam o formato Markdown com 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 (obrigatório):

• name: identificador do subagente usado nas @-menções
• description: descrição em uma linha do propósito do subagente

Seção do system prompt: Conteúdo em Markdown que define o comportamento do subagente:

• Personalidade e tom
• Abordagem de interpretação das tarefas
• Preferências de formato de saída
• Princípios de tomada de decisão

Política de invocação (obrigatória):

Invocation policy (strict|flexible): Policy description

• strict: invocar apenas quando solicitado explicitamente pelo usuário
• flexible: permitir a invocação automática com base em padrões de tarefa

Diretrizes de uso:

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

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

Exemplos 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 comuns para subagentes personalizados

Configuração de comportamento de subagentes (padrão AGENTS.md)

Embora o AGENTS.md sirva principalmente como arquivo de regras do projeto (consulte Sistemas de regras), ele também pode definir o comportamento de subagentes específico do projeto.

Princípios de design do system prompt

Seja específico e diretivo: Defina expectativas exatas de comportamento em vez de orientações genéricas.

Bom:

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

Evite:

Try to optimize code when possible

Estabeleça personalidade e tom: Crie "personas" distintas otimizadas para propósitos específicos:

You are a performance optimization specialist.

Defina princípios de tomada de decisão: Oriente como o subagente deve lidar com trade-offs:

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

Especifique o formato de saída: Controle como os resultados são apresentados:

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

Configuração da política de invocação

Política strict:

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

Use quando:

• O subagente lida com operações sensíveis (revisões de segurança, migrações de banco de dados)
• O usuário deve decidir conscientemente quando invocar
• A invocação automática poderia ser disruptiva

Política flexible:

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

Use quando:

• O subagente fornece contexto útil sem causar interrupção
• A invocação automática melhora a eficiência do fluxo de trabalho
• Os padrões de tarefa são claramente identificáveis

Melhores práticas para as diretrizes de uso:

Seção "When to use":

• Seja específico sobre os cenários de gatilho
• Inclua exemplos de prompts que devem invocar o subagente
• Descreva as características das tarefas que correspondem à especialização do subagente

Seção "When NOT to use":

• Liste explicitamente as exclusões para evitar invocações inadequadas
• Esclareça os limites em relação a subagentes relacionados
• Evite a expansão indevida de escopo

Roteamento e despacho de tarefas

O sistema multi-subagente do Verdent permite a execução paralela de tarefas com roteamento automático e coordenação entre agentes especializados.

Componentes da arquitetura

Agente principal (orquestrador): O agente principal analisa as solicitações do usuário, decompõe tarefas complexas e delega o trabalho especializado aos subagentes apropriados. Ele mantém o contexto da conversa e coordena os resultados dos subagentes.

Pool de subagentes: Conjunto de subagentes disponíveis (padrão e personalizados) que podem ser invocados automática ou manualmente. Cada um opera de forma independente com contexto isolado.

Roteamento automático de tarefas: Quando o agente principal detecta padrões de tarefa que correspondem às especializações dos subagentes, ele despacha o trabalho automaticamente:

• Perguntas de exploração da base de código → subagente Explorer
• Solicitações de revisão de segurança → subagente Code-reviewer
• Verificações de validação → subagente Verifier

Execução paralela: Vários subagentes podem ser executados simultaneamente em operações complexas. Exemplo: o subagente Explorer pesquisa na base de código enquanto o Code-reviewer analisa a segurança ao mesmo tempo, entregando resultados mais rápidos.

Consolidação de resultados: As saídas dos subagentes são retornadas ao agente principal, que sintetiza os resultados e apresenta respostas unificadas ao usuário.

Monitoramento de subagentes

Acompanhe o uso e o desempenho dos subagentes pela Chat View, onde o Verdent exibe as operações e os resultados dos subagentes.

Métodos de monitoramento

Indicadores na Chat View:

• As invocações de subagentes aparecem no histórico da conversa
• Indicadores de progresso mostram quando os subagentes estão em execução
• Os resultados identificam explicitamente qual subagente forneceu a saída

Seção de saídas dos subagentes: Exibição dedicada para:

• Resultados da execução de tarefas pelos subagentes
• Indicadores de progresso para tarefas paralelas
• Resumos consolidados quando as tarefas são concluídas

Atribuição das respostas: O Verdent atribui as descobertas a subagentes específicos nas respostas, deixando claro qual agente realizou cada análise ou busca.

Visibilidade e transparência

Transparência das operações: O Verdent mostra:

• Qual subagente foi invocado
• Se a invocação foi automática ou manual
• O motivo da delegação da tarefa
• O status de execução do subagente

Verificação da especificação manual: Quando você usa @-menções, o Verdent confirma que o subagente especificado está lidando com a tarefa, garantindo que suas preferências de roteamento sejam respeitadas.

Veja também