Subagentes no Claude Code SDK são IAs especializadas que são orquestradas pelo agente principal. Use subagentes para gerenciamento de contexto e paralelização. Este guia explica como aplicações SDK interagem com e utilizam subagentes que são criados através de arquivos markdown.

​
Visão Geral

Subagentes são criados exclusivamente através da abordagem baseada em sistema de arquivos, colocando arquivos markdown com frontmatter YAML em diretórios designados. O SDK pode então invocar esses subagentes pré-definidos durante a execução.

​
Benefícios de Usar Subagentes

​
Gerenciamento de Contexto

Subagentes mantêm contexto separado do agente principal, prevenindo sobrecarga de informações e mantendo interações focadas. Este isolamento garante que tarefas especializadas não poluam o contexto da conversa principal com detalhes irrelevantes. Exemplo: Um subagente research-assistant pode explorar dezenas de arquivos e páginas de documentação sem bagunçar a conversa principal com todos os resultados de busca intermediários - retornando apenas as descobertas relevantes.

​
Paralelização

Múltiplos subagentes podem executar simultaneamente, acelerando dramaticamente fluxos de trabalho complexos. Exemplo: Durante uma revisão de código, você pode executar subagentes style-checker, security-scanner, e test-coverage simultaneamente, reduzindo o tempo de revisão de minutos para segundos.

​
Instruções e Conhecimento Especializados

Cada subagente pode ter prompts de sistema personalizados com expertise específica, melhores práticas e restrições. Exemplo: Um subagente database-migration pode ter conhecimento detalhado sobre melhores práticas SQL, estratégias de rollback e verificações de integridade de dados que seriam ruído desnecessário nas instruções do agente principal.

​
Restrições de Ferramentas

Subagentes podem ser limitados a ferramentas específicas, reduzindo o risco de ações não intencionais. Exemplo: Um subagente doc-reviewer pode ter acesso apenas às ferramentas Read e Grep, garantindo que ele possa analisar mas nunca modificar acidentalmente seus arquivos de documentação.

​
Criando Subagentes

Subagentes são definidos como arquivos markdown em diretórios específicos:
  • Nível de projeto: .claude/agents/*.md - Disponível apenas no projeto atual
  • Nível de usuário: ~/.claude/agents/*.md - Disponível em todos os projetos

​
Formato do Arquivo

Cada subagente é um arquivo markdown com frontmatter YAML: 
---
name: code-reviewer
description: Especialista em revisão de código. Use para revisões de qualidade, segurança e manutenibilidade.
tools: Read, Grep, Glob, Bash  # Opcional - herda todas as ferramentas se omitido
---

O prompt de sistema do seu subagente vai aqui. Isso define o papel,
capacidades e abordagem do subagente para resolver problemas.

Inclua instruções específicas, melhores práticas e quaisquer restrições
que o subagente deve seguir.

​
Campos de Configuração

CampoObrigatórioDescrição
nameSimIdentificador único usando letras minúsculas e hífens
descriptionSimDescrição em linguagem natural de quando usar este subagente
toolsNãoLista separada por vírgulas de ferramentas permitidas. Se omitido, herda todas as ferramentas

​
Como o SDK Usa Subagentes

Ao usar o Claude Code SDK, subagentes definidos no sistema de arquivos ficam automaticamente disponíveis. Claude Code irá:
  1. Auto-detectar subagentes dos diretórios .claude/agents/
  2. Invocá-los automaticamente baseado na correspondência de tarefas
  3. Usar seus prompts especializados e restrições de ferramentas
  4. Manter contexto separado para cada invocação de subagente
O SDK respeita a configuração do sistema de arquivos - não há forma programática de criar subagentes em tempo de execução. Todos os subagentes devem ser definidos como arquivos antes da execução do SDK.

​
Exemplos de Subagentes

Para exemplos abrangentes de subagentes incluindo revisores de código, executores de teste, debuggers e auditores de segurança, veja o guia principal de Subagentes. O guia inclui configurações detalhadas e melhores práticas para criar subagentes eficazes.

​
Padrões de Integração do SDK

​
Invocação Automática

O SDK irá automaticamente invocar subagentes apropriados baseado no contexto da tarefa. Certifique-se de que o campo description do seu subagente indique claramente quando ele deve ser usado: 
---
name: performance-optimizer
description: Use PROATIVAMENTE quando mudanças de código podem impactar performance. DEVE SER USADO para tarefas de otimização.
tools: Read, Edit, Bash, Grep
---

​
Invocação Explícita

Usuários podem solicitar subagentes específicos em seus prompts: 
// Ao usar o SDK, usuários podem solicitar explicitamente subagentes:
const result = await query({
  prompt: "Use o subagente code-reviewer para verificar o módulo de autenticação"
});

​
Restrições de Ferramentas

Subagentes podem ter acesso restrito a ferramentas através do campo tools:
  • Omitir o campo - Subagente herda todas as ferramentas disponíveis (padrão)
  • Especificar ferramentas - Subagente pode usar apenas ferramentas listadas
Exemplo de um subagente de análise somente leitura: 
---
name: code-analyzer
description: Análise estática de código e revisão de arquitetura
tools: Read, Grep, Glob  # Sem permissões de escrita ou execução
---

Você é um analista de arquitetura de código. Analise estrutura de código,
identifique padrões e sugira melhorias sem fazer mudanças.

​
Documentação Relacionada