agents
.
Visão Geral
Subagentes podem ser definidos de duas maneiras ao usar o SDK:- Programaticamente - Usando o parâmetro
agents
nas suas opções dequery()
(recomendado para aplicações SDK) - Baseado em sistema de arquivos - Colocando arquivos markdown com frontmatter YAML em diretórios designados (
.claude/agents/
)
agents
, que fornece uma experiência de desenvolvimento mais integrada para aplicações SDK.
Benefícios de Usar Subagentes
Gerenciamento de Contexto
Subagentes mantêm contexto separado do agente principal, prevenindo sobrecarga de informações e mantendo as interações focadas. Este isolamento garante que tarefas especializadas não poluam o contexto da conversa principal com detalhes irrelevantes. Exemplo: Um subagenteresearch-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 os achados 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 subagentesstyle-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 subagentedatabase-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 subagentedoc-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
Definição Programática (Recomendada)
Defina subagentes diretamente no seu código usando o parâmetroagents
:
Configuração AgentDefinition
Campo | Tipo | Obrigatório | Descrição |
---|---|---|---|
description | string | Sim | Descrição em linguagem natural de quando usar este agente |
prompt | string | Sim | O prompt de sistema do agente definindo seu papel e comportamento |
tools | string[] | Não | Array de nomes de ferramentas permitidas. Se omitido, herda todas as ferramentas |
model | 'sonnet' | 'opus' | 'haiku' | 'inherit' | Não | Substituição de modelo para este agente. Padrão para modelo principal se omitido |
Definição Baseada em Sistema de Arquivos (Alternativa)
Você também pode definir subagentes 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
agents
) têm precedência sobre agentes baseados em sistema de arquivos com o mesmo nome.
Como o SDK Usa Subagentes
Ao usar o Claude Agent SDK, subagentes podem ser definidos programaticamente ou carregados do sistema de arquivos. Claude irá:- Carregar agentes programáticos do parâmetro
agents
nas suas opções - Auto-detectar agentes do sistema de arquivos dos diretórios
.claude/agents/
(se não substituído) - Invocá-los automaticamente baseado na correspondência de tarefas e na
description
do agente - Usar seus prompts especializados e restrições de ferramentas
- Manter contexto separado para cada invocação de subagente
agents
) têm precedência sobre agentes baseados em sistema de arquivos com o mesmo nome.
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 SDK
Invocação Automática
O SDK irá automaticamente invocar subagentes apropriados baseado no contexto da tarefa. Garanta que o campodescription
do seu agente indique claramente quando ele deve ser usado:
Invocação Explícita
Usuários podem solicitar subagentes específicos nos seus prompts:Configuração Dinâmica de Agente
Você pode configurar agentes dinamicamente baseado nas necessidades da sua aplicação:Restrições de Ferramentas
Subagentes podem ter acesso restrito a ferramentas via campotools
:
- Omitir o campo - Agente herda todas as ferramentas disponíveis (padrão)
- Especificar ferramentas - Agente pode usar apenas ferramentas listadas
Combinações Comuns de Ferramentas
Agentes somente leitura (análise, revisão):Documentação Relacionada
- Guia Principal de Subagentes - Documentação abrangente de subagentes
- Guia de Configuração SDK - Visão geral das abordagens de configuração
- Configurações - Referência de arquivo de configuração
- Comandos Slash - Criação de comandos personalizados