Os subagentes são uma das adições mais úteis ao ecossistema Claude Code / Claude Agent: eles permitem dividir fluxos de trabalho complexos em "equipes" de IA menores e especializadas, preservar o contexto do thread principal e limitar com segurança o acesso às ferramentas. Este artigo explica o que são subagentes, como criá-los e invocá-los (CLI, sistema de arquivos e SDK), o princípios de design você deve seguir ao construí-los e código de amostra concreto você pode copiar e adaptar.
O que são subagentes?
A subagente é um assistente de IA pré-configurado e de escopo restrito ao qual o Claude Code (ou o SDK do Agente Claude) pode delegar trabalho. Cada subagente:
- Tem um nome único e uma descrição clara do propósito.
- Corre em seu janela de contexto próprio separado da conversa principal (para que longas cadeias de detalhes não poluam o contexto do orquestrador).
- Pode ser configurado com um conjunto limitado de ferramentas (leitura/gravação de arquivos, bash, grep, ferramentas MCP, etc.) e com uma escolha de modelo específica.
- Contém um prompt do sistema (a personalidade e as instruções do subagente) que orienta o comportamento e as restrições.
Essas propriedades tornam os subagentes ideais para tarefas que exigem muitos tokens (pesquisa, busca em grandes logs), que exigem segurança (varredura ou ferramentas potencialmente destrutivas) ou que são repetitivas e bem especificadas (verificação de estilo, execução de testes).
O Anthropic tem iterado rapidamente: o Claude Code CLI e o Agent SDK foram refatorados e estendidos para o SDK do Agente Claude, o suporte a plugins foi introduzido para agrupar agentes e personalizações relacionadas (comandos slash, servidores MCP, ganchos) e Competências Fornece uma maneira de empacotar fluxos de trabalho de domínio para reutilização em Claude.ai, Claude Code e Agent SDK. Essas atualizações facilitam a compartilhar, instalar e versionar subagentes entre equipes e projetos. Se você planeja criar fluxos de trabalho de produção, deve avaliar o empacotamento de plugins/habilidades e os padrões de implantação baseados em SDK.
Por que os subagentes são importantes
Três razões pelas quais são imediatamente úteis:
- Preservação do contexto — buscas longas ou ruidosas, execuções de testes ou varreduras ocorrem dentro de um subagente, em vez de sobrecarregar o contexto primário. Isso reduz o desperdício de tokens e facilita o raciocínio sobre os resultados.
- Conhecimento especializado — você pode codificar o conhecimento e o comportamento do domínio em um prompt do sistema adaptado à tarefa (por exemplo, um
security-auditorque se concentra em segredos, problemas de dependência e uso inseguro de shell). - Permissões mais seguras — limitar ferramentas por subagente reduz o raio de explosão (um revisor de documentos pode ter ferramentas somente leitura; um executor de testes pode ter
Bashmas nãoEdit). - Paralelização: Você pode ativar vários subagentes para serem executados simultaneamente (por exemplo:
style-checker,security-scanner,test-runner) e então coletar seus breves resultados — uma grande vitória para verificações independentes e caras.
Pré-requisitos para usar Subagentes no Claude Code
Antes de começar a criar subagentes, certifique-se de ter o seguinte em vigor:
1) Claude Code instalado e autenticado
Instale o Claude Code CLI ou use as integrações web/IDE. Documentação de início rápido e configuração do CometAPI listar métodos de instalação suportados (pacote global npm ou instaladores nativos) e mostrar como verificar sua instalação com claude --version / claude doctor. Você também precisará de um CometAPI conta (usar a chave do CometAPI para acessar o código do Claude é mais barato e mais conveniente do que o modelo oficial), conforme observado no Início rápido.
2) Nó / ambiente (para alguns caminhos de instalação) e ferramentas básicas de shell
Se você instalar através do pacote npm, deverá ter o Node.js (Node 18+ é comum em exemplos). Se pretende usar o SDK do Agente (JavaScript/TypeScript ou Python), precisará de um projeto com a dependência do SDK instalada. Muitos tutoriais pressupõem ferramentas padrão de desenvolvedor (git, bash, opcional gh CLI para fluxos de trabalho do GitHub).
3) Layout do projeto e CLAUDE.md
A melhor prática é manter os documentos auxiliares no nível do repositório (CLAUDE.md) e colocar agentes com escopo de projeto em .claude/agents/ para que os colegas de equipe os herdem. Os arquivos CLAUDE.md são inseridos automaticamente no contexto do Claude e ajudam a orientar o comportamento de forma consistente em todas as sessões. Cada subagente é um arquivo Markdown com frontmatter YAML. Exemplo mínimo:
---
name: code-reviewer
description: Expert code review specialist. Use PROACTIVELY after code changes to check security, style, and maintainability.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer. When invoked:
1. Run `git diff` to identify modified files.
2. Focus review on changed code paths.
3. List security issues, probable false positives, and suggested fixes.
4. Provide a short, prioritized action list.
Return results in JSON with fields: summary, issues.
nameé um identificador em minúsculas.descriptionorienta a invocação e a correspondência automáticas.toolsrestringe o acesso à ferramenta (omite herdar tudo).modelpode sersonnet,opus,haiku, ouinherit.
4) Permissões e servidores MCP (opcional, mas comum)
Se seus fluxos de trabalho utilizam servidores MCP (Model Context Protocol) ou ferramentas externas (Puppeteer, Sentry, ferramentas REST personalizadas), certifique-se de que seus servidores MCP estejam configurados e acessíveis. Para operações sensíveis (write, bash, git commit), seja criterioso quanto à lista de permissões e por agente. tools escopo.
Como criar subagentes no Claude Code
Você pode criar subagentes de três maneiras principais: por meio da CLI interativa (/agents), como arquivos markdown do sistema de arquivos ou programaticamente por meio do SDK do Agente. Abaixo estão as opções passo a passo:
Claude Code oferece suporte a três maneiras práticas de criar subagentes:
- CLI interativo
/agentsUI — mais rápido para criação iterativa dentro de uma sessão. - Baseado em sistema de arquivos — criar arquivos Markdown com frontmatter YAML em
.claude/agents/(nível de projeto) ou~/.claude/agents/(nível de usuário). Os agentes de projeto têm maior prioridade. - Programático (SDK do Agente) — definir subagentes no código por meio de
agentsparâmetro quando você chamaquery(); recomendado para aplicativos baseados em SDK. Essa abordagem é ideal quando subagentes precisam ser criados dinamicamente ou incorporados em um aplicativo.
Fluxo interativo rápido (primeira etapa recomendada)
- Inicie o Claude Code no seu terminal ou abra a paleta de comandos no VS Code.
- Execute a interface dos subagentes com o comando slash:
/agents
- Escolha Criar novo agente, escolha o escopo em nível de projeto ou de usuário, preencha o nome/descrição/ferramentas/prompt do sistema e salve. Você pode gerar um rascunho com o Claude e depois refiná-lo. Depois de salvo, o agente fica disponível em
/agentse pode ser invocado explicitamente ou automaticamente.
Subagentes baseados em sistema de arquivos (Markdown + YAML frontmatter)
Os subagentes são armazenados como arquivos Markdown com frontmatter YAML. Coloque-os em:
- Escopo do projeto:
.claude/agents/*.md(prioridade máxima) - Escopo do usuário:
~/.claude/agents/*.md
Estrutura básica do arquivo:
---
name: code-reviewer
description: "Review recent code changes for security and style."
tools: Read, Grep, Glob, Bash # optional; omit to inherit
model: sonnet # optional; or 'inherit'
---
You are a senior code reviewer with expertise in security, performance, and best practices.
When reviewing:
- Identify security vulnerabilities
- Prioritize clarity and maintainability
- Always provide concise examples and suggested fixes
- If unsure, ask for the minimal reproducible snippet
Algumas notas de implementação:
namedeve ser escrito em letras minúsculas com hífens.- Omitindo
toolspermitirá que o subagente herde todas as ferramentas do thread principal; listar explicitamente as ferramentas impõe um modelo de privilégio mínimo. - Uso
model: 'inherit'para comportamento consistente com o thread principal ou especifique um alias de modelo (por exemplo,sonnet,opus,haiku).
Definição CLI JSON (uso ad hoc/sessão)
Você pode definir subagentes temporários em linha ao iniciar uma sessão:
claude --agents '{
"code-reviewer": {
"description": "Expert code reviewer.",
"prompt": "You are a senior code reviewer. Focus on security and best practices.",
"tools": ,
"model": "sonnet"
}
}'
Os agentes definidos pela CLI são úteis para execuções com script ou experimentos; eles têm menor prioridade que os agentes de projeto, mas maior que os agentes de usuário.
Definição programática (Agent SDK — recomendado para aplicativos)
Se você estiver criando um aplicativo ou automação, defina subagentes programaticamente por meio do SDK do agente agents parâmetro (esta é a opção mais integrada). Exemplo (TypeScript):
import { query } from '@anthropic-ai/claude-agent-sdk';
async function runReview() {
const result = await query({
prompt: "Assess the authentication module for security issues",
options: {
agents: {
"code-reviewer": {
description: "Expert code review specialist",
prompt: `You are a code review specialist...`,
tools: ,
model: "sonnet"
},
"test-runner": {
description: "Runs the test suite and analyzes failures",
prompt: `You run tests and summarize failures...`,
tools: ,
model: "sonnet"
}
}
}
});
console.log(result);
}
O SDK também aceita agentes baseados em sistema de arquivos (ele carregará .claude/agents/ arquivos) se preferir esse padrão. Agentes programáticos são poderosos para fluxos de trabalho dinâmicos e integração de CI.
Para Python, o claude-agent-sdk o pacote suporta padrões semelhantes: você pode usar query() or ClaudeSDKClient e configurar opções, ferramentas e servidores MCP programaticamente. Consulte o repositório do Python SDK para obter exemplos de início rápido.
Como invocar subagentes
Delegação automática
Claude Code pode automaticamente Escolha um subagente quando um prompt do usuário corresponder à finalidade do subagente. Isso é útil para orquestração em segundo plano, onde o agente principal encaminha tarefas para o especialista certo automaticamente. Conte com descrições claras dos subagentes e prompts de sistema focados para melhorar a precisão da seleção automática.
Invocação explícita (recomendada para maior clareza)
Você pode invocar explicitamente um agente na conversa:
> Use the code-reviewer subagent to check my recent changes
A invocação explícita é determinística e recomendada para fluxos de produção nos quais você deseja evitar delegação inesperada.
Padrões do orquestrador SDK
Padrões comuns em aplicativos SDK:
- Garfo + reunir: Inicie vários subagentes em paralelo, colete a resposta concisa de cada agente e, em seguida, resuma/mescle os resultados no agente principal.
- Loop de supervisor: O orquestrador atribui tarefas aos subagentes, inspeciona os resultados e os aceita ou solicita recálculo/esclarecimento.
- Execução em sandbox: Dê capacidades potencialmente perigosas (implantar, executar scripts) a um agente fortemente restrito e exija ganchos de aprovação humana explícitos antes da execução.
Esses padrões são mapeados para implementações práticas usando o gerenciamento de sessão, ganchos e ferramentas MCP do Agent SDK.
Como criar subagentes úteis, seguros e combináveis
1) Responsabilidade única e instruções claras
Cada subagente deve ter um propósito claro e um prompt de sistema que especifique limites, critérios de sucesso e formato de saída. Se a saída desejada for estruturada (JSON, lista com marcadores, patch de código), instrua o subagente com precisão para reduzir erros de análise.
2) Menor privilégio para ferramentas
Conceda apenas as ferramentas de que um subagente necessita. Por exemplo, um revisor de documentos não precisa Write or BashDefina como somente leitura sempre que possível e aumente as permissões de ferramentas explicitamente quando necessário. Isso reduz riscos e simplifica a auditoria.
3) Retornar saídas compactas e estruturadas
Os subagentes devem retornar respostas concisas e finais em vez de rastros de pensamento de longa duração. Um padrão comum é: realizar trabalho pesado dentro do contexto do subagente e, em seguida, retornar um breve resumo com anexos (patches, referências de arquivo, JSON). Isso maximiza a eficiência do contexto para o orquestrador.
4) Testabilidade e versionamento
Armazene arquivos de subagentes no controle de versão, crie testes de CI que testem execuções reais em pequenas entradas e fixe modelos/conjuntos de ferramentas. Se você depende de Habilidades e plugins, adote os padrões de controle de versão/mercado de plugins para gerenciar atualizações e reversões.
5) Ganchos de auditoria e pontos de verificação com intervenção humana
Use ganchos do SDK para interceptar invocações de ferramentas (ganchos PreToolUse) e exigir aprovação humana para ações destrutivas. Registre todas as chamadas de ferramentas para auditorias reproduzíveis. O SDK fornece mecanismos de ganchos e permissões para dar suporte a esse padrão.
Exemplo de aplicação — um pequeno pipeline semelhante ao de produção
Abaixo está um exemplo compacto que mostra as peças típicas: um agente de sistema de arquivos, uma invocação de SDK que usa dois agentes (um para revisão, um para testes) e uma orquestração simples.
1) Agente do sistema de arquivos: .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Use PROACTIVELY after code changes. Perform security, style, and maintainability review on modified files.
tools: Read, Grep, Glob
model: inherit
---
You are a meticulous senior code reviewer. When invoked:
1. Run `git diff --name-only` to find modified files.
2. For each modified file, read and look for security issues, suspicious patterns, or maintainability problems.
3. Return JSON:
{
"summary": "one-line summary",
"issues": ,
"recommended_changes":
}
2) Orquestração programática (Node.js)
import { query } from '@anthropic-ai/claude-agent-sdk';
import fs from 'fs';
async function runPipeline() {
const result = query({
prompt: 'Run PR checks: security review then unit tests.',
options: {
agents: {
'code-reviewer': {
description: 'Use PROACTIVELY after code changes; output JSON with issues.',
prompt: fs.readFileSync('./.claude/agents/code-reviewer.md', 'utf8'),
tools: ,
model: 'sonnet'
},
'test-runner': {
description: 'Run test suite and summarize failing tests.',
prompt: `You are a test-runner. Execute tests and return JSON { summary, failing_tests[] }`,
tools:
}
}
}
});
for await (const message of result) {
// Implement streaming logic: messages may include subagent outputs
console.log(message);
}
}
runPipeline().catch(console.error);
Observações: da code-reviewer é armazenado no repositório para reutilização da equipe; a chamada do SDK demonstra que os agentes programáticos têm precedência e o tools o escopo evita gravações acidentais.
Tópicos e padrões avançados
Configuração dinâmica do agente
Crie fábricas de agentes parametrizadas que escolham modelos e conjuntos de ferramentas dependendo do ambiente (desenvolvimento vs. produção) ou níveis de gravidade (por exemplo, strict vs balanced modos de segurança). Os exemplos do SDK mostram como gerar definições de agentes em tempo de execução.
Paralelização
Crie vários agentes de análise somente leitura em paralelo (estilo, segurança, cobertura de testes) e agregue suas saídas JSON na thread principal. Isso reduz significativamente o tempo de execução de repositórios grandes.
Agentes fornecidos por plugin
Os plugins podem fornecer subagentes empacotados com o manifesto do plugin; eles aparecem em /agents juntamente com agentes personalizados e podem ser invocados explicitamente. Use isso para distribuir agentes padronizados entre as equipes.
Onde usar o código Claude cli é mais recomendado
Foi um anúncio emocionante que o CometAPI agora oferece suporte total ao poderoso Claude Code CLI. Você só precisa instalar o Claude Code e autenticar com a chave da API Comet obtida e o endereço base para usar o modelo da API Comet no Claude Code.
Por que usar o código Claude através do CometAPI?
Principais recursos de inteligência artificial: gere, depure e otimize código facilmente usando modelos criados especificamente para desenvolvedores.
- Seleção flexível de modelos: nossa ampla gama de modelos permite que você desenvolva com mais facilidade.
- Integração perfeita: APIs sempre disponíveis. Integre o Claude Code diretamente ao seu fluxo de trabalho atual em minutos.
- Usar o Claude Code via CometAPI economizará mais custos. A API Claude fornecida pela CometAPI tem 20% de desconto sobre o preço oficial e é atualizada com o modelo mais recente pelo oficial.
Pronto para usar o Claude Code CLI? consulte o Guia de API para instruções detalhadas.
Se você quiser saber mais dicas, guias e novidades sobre IA, siga-nos em VK, X e Discord!
Veja também Como instalar e executar o Claude Code via CometAPI?
Considerações finais
Tratar subagentes como micropersonas reutilizáveis e versionadas. Comece pequeno: faça um doc-reviewer e uma test-runner para um repositório, verifique-os em .claude/agents/, e automatizá-los em CI usando headless claude -p. Itere seus prompts, adicione saídas estruturadas e restrinja as permissões de ferramentas.
O modelo mental que mais ajuda: imagine Claude como gerente de projeto e os subagentes como especialistas da equipe. O gerente delega tarefas claramente formuladas, agrega as entregas dos especialistas e redige o relatório final. Com o tempo, você verá melhorias na confiabilidade, na testabilidade e na capacidade de automatizar grandes partes dos fluxos de trabalho dos desenvolvedores.