---
title: Gerenciamento de subagentes
description: Entenda e gerencie subagentes no Verdent
---
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.
**Especialização:** verificações e validações rápidas de código
**Capacidades:**
- Valida a lógica do código
- Verifica a correção da sintaxe
- Confirma a implementação em relação aos requisitos
**Uso:**
Referencie durante tarefas de codificação:
```
@Verifier check this authentication logic
```
**Ideal para:** validação rápida sem a sobrecarga de uma revisão de código completa
**Especialização:** exploração e navegação rápidas da base de código
**Capacidades:**
- Encontra arquivos por padrão ou nome
- Pesquisa código por palavras-chave/funções
- Responde a perguntas sobre arquitetura
- Identifica onde a funcionalidade está implementada
**Uso:**
Invocado automaticamente para perguntas sobre a base de código ou quando solicitado explicitamente:
```
@Explorer find all API endpoints
```
**Ideal para:**
- Entender bases de código desconhecidas
- Localizar implementações específicas
- Análise de arquitetura
**Desempenho:** eficiente no uso de tokens, podendo executar várias instâncias em paralelo para buscas complexas
**Especialização:** avaliação da qualidade do código
**Capacidades:**
- Examina proativamente código novo e modificado em busca de vulnerabilidades de segurança
- Identifica problemas de manutenibilidade
- Detecta problemas de desempenho
**Uso:**
Referencie para verificações de qualidade:
```
@Code-reviewer review this authentication flow
```
**Ideal para:**
- Revisões pré-commit
- Identificar problemas antes da integração
- Garantir os padrões de qualidade do código
---
### 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
Subagentes personalizados podem ser invocados automaticamente com base nas diretrizes "When to use" definidas na política de invocação do system prompt do subagente. Os detalhes sobre a configuração dos padrões de gatilho estão em desenvolvimento.
---
## 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
**Recomendado para iniciantes**
1. Clique em **Settings** → **Subagents**
2. Selecione "Create new subagent"
3. Defina o nome, a descrição e o system prompt do subagente
4. Configure a política de invocação e as diretrizes de uso
5. Salve no diretório `~/.verdent/subagents/`
Esse método oferece uma interface guiada para criar subagentes com validação e prompts úteis.
**Recomendado para usuários avançados**
1. Navegue até `~/.verdent/subagents/`
2. Crie um arquivo markdown (por exemplo, `security-reviewer.md`)
3. Adicione o frontmatter YAML com `name` e `description`
4. Escreva o system prompt que define o comportamento
5. Especifique a política de invocação e as diretrizes "When to use"
Esse método oferece mais controle e é mais rápido para usuários familiarizados com a estrutura de arquivos.
Compartilhe subagentes personalizados entre projetos armazenando-os em ~/.verdent/subagents/. Eles ficarão disponíveis em todos os espaços de trabalho.
---
### Estrutura do arquivo
Os arquivos de subagentes personalizados usam o formato Markdown com 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 (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
```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 de uso:** gerar automaticamente documentação completa de API analisando handlers de rotas, controllers e definições de schema.
```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 de uso:** evitar incidentes em produção identificando operações de banco de dados arriscadas antes da implantação.
```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 de uso:** garantir que os apps web atendam aos padrões de acessibilidade antes da implantação.
---
### Casos de uso comuns para subagentes personalizados
**Expertise específica de domínio**
- **Cálculos financeiros:** subagente especializado em conformidade tributária e regulamentações financeiras
- **Conformidade com HIPAA na saúde:** revisar código quanto aos padrões de tratamento de dados de pacientes
- **Criptografia:** analisar implementações de segurança em relação às melhores práticas
Ideal para setores com requisitos de conhecimento especializado e restrições regulatórias.
**Fluxos de trabalho específicos de equipe**
- **Aplicador de estilo de código:** verificar em relação a padrões de codificação específicos da equipe além das regras do linter
- **Consistência de documentação:** garantir que a documentação siga os modelos e o tom da equipe
- **Auditor de dependências:** monitorar o uso de pacotes de terceiros em relação a listas aprovadas
Aplique as convenções da equipe e mantenha a consistência em projetos colaborativos.
**Especialistas em stacks de tecnologia**
- **Otimizador de desempenho do React:** identificar re-renderizações desnecessárias e oportunidades de memoização
- **Otimizador de consultas SQL:** analisar e melhorar o desempenho das consultas ao banco de dados
- **Revisor de configuração do Docker:** validar as melhores práticas de conteinerização
Expertise profunda em frameworks, linguagens ou tecnologias de infraestrutura específicos.
**Garantia de qualidade**
- **Analisador de cobertura de testes:** identificar caminhos de código não testados e sugerir cenários de teste
- **Revisor de tratamento de erros:** garantir um tratamento abrangente de exceções
- **Aplicador de padrões de logging:** verificar as práticas de logging para depuração e monitoramento
Verificações de qualidade automatizadas para manter os padrões de confiabilidade e manutenibilidade do código.
**Conformidade e segurança**
- **Verificador de conformidade com GDPR:** revisar o tratamento de dados quanto aos requisitos de privacidade
- **Scanner de vulnerabilidades de segurança:** detecção especializada de problemas específicos de frameworks
- **Auditor de conformidade de licenças:** verificar dependências quanto à compatibilidade de licenças
Garanta a adesão aos requisitos legais, de segurança e de licenciamento antes da implantação.
**Necessidades específicas do projeto**
- **Modernizador de código legado:** identificar padrões obsoletos e sugerir alternativas modernas
- **Assistente de migração:** orientar atualizações de versão de framework ou linguagem
- **Aplicador de orçamento de desempenho:** monitorar tamanhos de bundle e tempos de carregamento em relação a limites
Soluções personalizadas adaptadas aos desafios únicos do projeto e à gestão de dívida técnica.
---
## 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](/docs/verdent-for-vscode/agents-rules/rule-systems)), 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.
Seja específico e diretivo nos system prompts; "Faça o profiling antes de otimizar" é melhor do que "Tente otimizar quando possível".
**Bom:**
```markdown
Analysis approach:
- Profile before optimizing
- Focus on algorithmic improvements
- Provide before/after benchmarks
```
**Evite:**
```markdown
Try to optimize code when possible
```
**Estabeleça personalidade e tom:**
Crie "personas" distintas otimizadas para propósitos específicos:
```markdown
You are a performance optimization specialist.
```
**Defina princípios de tomada de decisão:**
Oriente como o subagente deve lidar com trade-offs:
```markdown
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:
```markdown
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:**
```markdown
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:**
```markdown
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.
A execução paralela de subagentes acelera tarefas complexas; o Explorer pode pesquisar enquanto o Code-reviewer analisa simultaneamente.
**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.
Informações detalhadas sobre agendamento de execução, prioridade, limites máximos de concorrência, tratamento de erros e alocação de recursos dos subagentes estão em desenvolvimento. Entre em contato com o suporte para questões específicas de arquitetura.
---
## 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.
Recursos avançados de monitoramento, incluindo logs de execução detalhados, métricas de desempenho (tempo de execução, uso de tokens), rastreamento histórico de invocações, configurações de visibilidade de atividades e painéis de análise de uso, estão em desenvolvimento.
---
## Veja também
Configure o comportamento do Verdent por meio de regras de usuário, regras de projeto e regras de plano
Referência completa das ferramentas e capacidades disponíveis