O que são Subagentes no Claude Code? O que você precisa saber

Subagentes (frequentemente escritos subagentes or subagentes) são um dos avanços práticos mais claros nas ferramentas de desenvolvimento de agentes: eles permitem que você componha uma pequena equipe de assistentes de IA especializados dentro Código Claude, cada um com sua própria função, ferramentas e janela de contexto. A ideia é simples, mas poderosa — em vez de exigir que um modelo generalista faça tudo, você define agentes compactos e de propósito único para os quais o orquestrador principal delega trabalho (automaticamente ou quando você os solicita explicitamente). Isso muda a forma como você gerencia o contexto, as ferramentas e as compensações de custo/latência de fluxos de trabalho complexos.

O que são subagentes?

Definição curta. Um subagente é uma "personalidade" de IA pré-configurada e especializada em tarefas à qual Claude Code pode delegar uma tarefa. Cada subagente tem seu próprio prompt de sistema, sua própria janela de contexto (isolada), ferramentas explicitamente concedidas e, opcionalmente, uma seleção de modelo. Os subagentes podem ser criados no nível do projeto ou do usuário e invocados automaticamente por Claude ou explicitamente pelo usuário.

Propriedades principais de um subagente

Finalidade especializada e sistema rápido. Você descreve a função, as restrições e a abordagem do subagente em seu prompt do sistema para que ele se comporte de forma previsível em seu domínio restrito (por exemplo, revisor de código, depurador, cientista de dados).
Janela de contexto isolada. Cada subagente mantém seu próprio histórico e contexto de conversa, evitando que o contexto da thread principal seja poluído com detalhes de baixo nível. Isso é essencial para dimensionar fluxos de trabalho que, de outra forma, esgotariam o contexto de uma única conversa.
Escopo e permissões da ferramenta. Você pode conceder ou restringir quais ferramentas internas ou externas do Protocolo de Contexto do Modelo (MCP) um subagente pode usar. Este é um recurso crucial de segurança e governança.
Configuração como código. Os subagentes são definidos como arquivos Markdown com front matter YAML (nome, descrição, ferramentas, modelo) e armazenados no nível do projeto (.claude/agents/) ou nível de usuário (~/.claude/agents/). As definições do projeto têm precedência.

O que são delegação automática e invocação explícita

Claude Code pode automaticamente delegar tarefas aos subagentes quando seu prompt ou o subagente description corresponde à tarefa — ou você pode explicitamente solicitar um agente (por exemplo, > Use the code-reviewer subagent to check my recent changes). Faça o description orientado para a ação ("Use PROACTIVELY", "MUST BE USED") para estimular a delegação automática, duas maneiras complementares de usar subagentes no Claude Code:

Delegação automática — Claude inspeciona a solicitação e delega o trabalho correspondente a um subagente proativamente.
Invocação explícita — você chama um subagente pelo nome em seu prompt/comando (por exemplo, Use the code-reviewer subagent to check my changes).

Ambas as abordagens têm diferentes compensações em termos de UX e engenharia. Abaixo, descrevo cada uma delas.

Delegação automática

Como isso parece para os usuários. Você emite um comando de alto nível (por exemplo, “Prepare uma auditoria de segurança para esta nova biblioteca”), e Claude detecta que um ou mais subagentes são adequados com base no description campo em suas configurações. Se configurado para uso proativo, o subagente é despachado automaticamente e retorna resultados como saídas estruturadas.

Por que as equipes o utilizam.

Isso reduz a carga cognitiva — você não precisa lembrar ou digitar o nome de cada subagente.
Ele cria uma integração mais tranquila para fluxos de trabalho compartilhados, onde tarefas específicas devem sempre ser tratadas pelo mesmo especialista.

Ressalvas.

Você deve projetar o description e o sistema avisa deliberadamente para que Claude selecione de forma confiável o subagente correto.
Delegação excessivamente ansiosa pode aumentar o uso de tokens e o ruído se muitos subagentes forem ativados para tarefas semelhantes; crie suas descrições de forma conservadora.

Invocação explícita

Como isso parece para os usuários. Você chama explicitamente um subagente: > Use the test-runner subagent to run the project tests. A orquestração é determinística: Claude invoca o subagente nomeado com suas permissões e prompt pré-configurados.

Por que as equipes o utilizam.

Controle total: você decide exatamente qual especialista será executado, o que simplifica a depuração e a reprodutibilidade.
Mais fácil raciocinar sobre custos e acesso a ferramentas em CI ou scripts automatizados.

Ressalvas.

Mais digitação e disciplina: desenvolvedores ou automação devem saber os nomes corretos dos subagentes.
Menos oportunista: você perde alguma conveniência, pois o agente principal teria detectado um bom subagente automaticamente.

Como funcionam os subagentes — visão geral técnica

Abaixo está uma visão prática e orientada à implementação do que acontece quando você cria e usa um subagente.

Definindo um subagente (configuração como código)

Um subagente é um arquivo Markdown com front-texto YAML. Os campos importantes incluem:

name — um id exclusivo em minúsculas (hifenizado)
description — descrição em linguagem natural usada para correspondência automática de delegação
tools — lista de vírgulas opcional de ferramentas permitidas (ou omitida para herdar todas as ferramentas)
model — alias opcional (sonnet, opus, haiku) ou inherit para usar o modelo da conversa principal

Um pequeno exemplo (conceitual, não literal dos documentos):

---
name: code-reviewer
description: Expert code reviewer. Proactively reviews code for quality, security, and maintainability.
tools: Read, Grep, Bash
model: inherit
---
You are a senior code reviewer. Focus on security, correctness, and maintainability.

Esses arquivos residem em .claude/agents/ (escopo do projeto) ou ~/.claude/agents/ (escopo do usuário). Os arquivos do projeto têm precedência, o que simplifica o compartilhamento e o controle de versão de subagentes.

Seleção de modelos e ferramentas

Campo do modelo: Você pode escolher um alias de modelo específico para o subagente ou deixá-lo herdar o modelo da conversa principal. Isso permite combinar compensações de custo/qualidade (por exemplo, usar um modelo mais barato para subagentes de varredura de dados grandes e um modelo de maior qualidade para síntese final).
Escopo da ferramenta: Fornecer a cada subagente um conjunto mínimo de ferramentas reduz o raio de explosão e simplifica o raciocínio sobre segurança. As ferramentas incluem as primitivas padrão do Claude Code (Read, Grep, Bash, Edit, etc.) e integrações fornecidas pelo MCP.

Comportamento de tempo de execução e tratamento de contexto

Quando Claude delega a um subagente, esse subagente recebe:

Seu prompt do sistema (o conteúdo YAML/Markdown).
Somente o contexto necessário (sua própria janela de contexto).
Acesso à ferramenta conforme permitido em sua configuração.

Como cada subagente mantém um contexto isolado, investigações longas ou análises de arquivos grandes podem ser decompostas em muitos contextos pequenos, em vez de forçar um único contexto a conter tudo — uma grande vitória tanto para a confiabilidade quanto para a interpretabilidade.

Padrões arquitetônicos para subagentes

A arquitetura mais comum é uma orquestrador (agente principal) que decompõe uma tarefa de alto nível, inicia vários subagentes e, em seguida, sintetiza ou verifica suas saídas. Dois padrões canônicos aparecem em ação:

1) Orquestrador + Especialistas

Um agente (o orquestrador) coordena múltiplos subagentes em paralelo ou em série. O orquestrador decide qual especialista chamar, agrega saídas, verifica a consistência e realiza a integração final. Essa é a abordagem comum de "gerente delega para membros da equipe" e corresponde a muitos exemplos e designs recomendados nos materiais de Claude Code. Os benefícios incluem paralelismo, separação mais clara de interesses e contenção de erros mais fácil (um subagente com bugs afeta apenas seu escopo).

Quando usar: tarefas complexas com subproblemas independentes (por exemplo, “gerar testes”, “executar análise estática”, “reescrever um módulo” e, em seguida, “integrar e executar testes de ponta a ponta”).

Trocas: a lógica de orquestração pode se tornar complexa; viagens de ida e volta extras podem aumentar ligeiramente a latência.

2) Especialistas em Pipeline / Encadeados

Aqui, os subagentes são organizados em uma sequência em que a saída de um se torna a entrada do próximo (por exemplo, spec → scaffold → implement → test → optimize). Isso é essencialmente uma composição de funções expressa como agentes — útil quando você precisa de transformações graduais e garantias rigorosas sobre como os dados fluem entre os estágios. É conceitualmente mais simples para fluxos de trabalho lineares e, às vezes, mais fácil de depurar.

Quando usar: transformações determinísticas em várias etapas (por exemplo, traduzir um documento de design em código estruturado, depois testes e, por fim, otimizações).

Trocas: menos natural para tarefas que exigem ampla exploração (pesquisa, brainstorming), e um único link quebrado pode paralisar todo o pipeline.

O que torna um subagente diferente de um mero prompt baseado em função?

1) Janelas de contexto separadas

Cada subagente tem seu próprio buffer de contexto que armazena trocas, arquivos e metadados relevantes para sua função. Isso evita que o contexto da sessão principal seja poluído por mensagens intermediárias ruidosas e também significa que você pode preservar — ou limitar — o histórico de cada recurso. É assim que o Claude Code permite que você mantenha contextos de alta intensidade e longa duração para tarefas especializadas sem pagar o custo simbólico ou a sobrecarga cognitiva de colocar tudo em um único prompt.

2) Prompts e personas do sistema

Os subagentes são criados com instruções em nível de sistema que definem sua função, tom e restrições (por exemplo, "Agir apenas como especialista em refatoração; não executar comandos de shell" ou "Gerar testes unitários no estilo pytest; usar apenas interfaces públicas"). Esses prompts funcionam como descrições de tarefas para o subagente e são aplicados em tempo de execução pelo tempo de execução do Claude Code.

3) Associações de ferramentas e escopo de permissão

Uma diferença prática crucial: os subagentes podem ter acesso concedido ou negado a ferramentas específicas — sistema de arquivos, execução de processos, APIs externas ou conjuntos de dados privilegiados. Isso torna os subagentes poderosos para Ultimo privilégio Projetos: um gerador de documentação pode ser bloqueado para executar comandos arbitrários, enquanto um subagente de CI recebe uma sandbox isolada. Muitas postagens da comunidade defendem o pareamento de subagentes com o Model Context Protocol (MCP) ou um servidor MCP baseado em ganchos para gerenciar o acesso seguro a segredos e E/S.

4) Escolha do modelo e compensações entre custo e desempenho

Como os subagentes são modulares, você pode atribuir diferentes modelos subjacentes dependendo da complexidade da tarefa. Use um modelo Sonnet de alta capacidade para raciocínio profundo ou um modelo Haiku leve para tarefas rápidas e repetitivas. Essa implantação heterogênea ajuda a equilibrar latência, custo de token e capacidade. As atualizações de produtos e artigos da comunidade da Anthropic enfatizam a implantação paralela de modelos menores para um dimensionamento econômico.

5) Padrões de comunicação

Os subagentes se comunicam com o orquestrador (ou entre si) por meio de mensagens estruturadas ou arquivos. Os padrões típicos incluem:

retornando uma carga útil JSON estruturada (preferida para orquestração programática),
escrevendo em um arquivo com escopo em um espaço de trabalho compartilhado,
ou enviar uma mensagem final formatada de volta ao orquestrador que inclua uma pontuação de confiança e justificativa.
Experimentos comunitários mostram que equipes preferem transferências explícitas e legíveis por máquinas para evitar ambiguidade.

Benefícios de desempenho

Os subagentes não são apenas um detalhe de design — eles oferecem desempenho prático e benefícios de qualidade quando usados corretamente.

1) Redução do tempo de processamento por meio do paralelismo

Ao despachar vários trabalhadores simultaneamente (por exemplo, um trabalhador por pasta de repositório, por microsserviço ou por bloco de dados), o orquestrador reduz o tempo decorrido necessário para concluir grandes tarefas compostas. Casos de uso como triagem de relatórios de bugs, geração de documentação para vários módulos ou auditoria de múltiplos serviços são opções naturais. Acelerações significativas nos fluxos de trabalho do desenvolvedor quando as cargas de trabalho são verdadeiramente paralelizáveis.

Ao atribuir a cada função seu próprio contexto, você evita o inchaço de prompts e reduz o risco de alucinações causadas por ruído histórico irrelevante. Isso significa menos falhas relacionadas ao contexto e resultados mais consistentes para tarefas especializadas. Artigos da comunidade e a própria pesquisa da Anthropic mostram que configurações multiagentes frequentemente superam agentes monolíticos em tarefas de amplitude. Uma avaliação interna da Anthropic relatou melhorias drásticas para tarefas de estilo de pesquisa usando uma arquitetura de agente líder + subagentes.

Observação: o paralelismo gera os melhores ganhos quando as subtarefas são independentes. Se os trabalhadores precisarem esperar constantemente uns pelos outros ou compartilhar estados pesados, você verá retornos decrescentes.

2) Melhor utilização do contexto e menor desperdício de tokens

Em vez de compactar todos os resultados de pesquisa intermediários em um único contexto global, os workers mantêm apenas o que é relevante dentro de sua própria janela e retornam resultados destilados. Isso reduz o consumo de tokens para o orquestrador e o risco de atingir os limites de contexto — uma vantagem prática ao trabalhar com grandes bases de código, logs longos ou grandes repositórios de documentos. A compactação/sumarização do SDK expande ainda mais a memória efetiva dos agentes de longa execução.

3) Precisão aprimorada por meio de instruções especializadas

Um subagente construído como um especialista com escopo restrito pode ser ajustado (por meio de seu prompt de sistema e conjunto de ferramentas) para otimizar a precisão em seu domínio: verificações de segurança, estilo de código ou extração de conformidade. Prompts com escopo restrito tendem a reduzir a alucinação, pois o espaço de ação permitido e os resultados esperados do agente são limitados. As organizações relatam resultados de maior qualidade para tarefas como revisão automatizada de código quando usam subagentes específicos de domínio em vez de pedir a um generalista para fazer tudo.

Como as equipes realmente usam subagentes — exemplos de fluxos de trabalho

Abaixo estão alguns exemplos concretos para tornar isso menos abstrato.

Exemplo A — Pipeline de refatoração (Orquestrador + Especialistas)

O Orchestrator recebe uma solicitação de “refatoração do componente X”.
Chamadas do orquestrador analysis-subagent (sem permissões de gravação) para identificar pontos críticos de complexidade e dependências arriscadas.
Chamadas do orquestrador refactor-subagent (escrever permissões em uma sandbox semelhante a uma ramificação) para produzir arquivos refatorados.
Chamadas do orquestrador test-gen-subagent (somente leitura no código) para produzir testes unitários.
O Orchestrator executa o CI com ci-runner-subagent (execução em sandbox) e agrega resultados para uma revisão humana.
Esse padrão isola cada fase, contém riscos e mantém as trilhas de auditoria organizadas.

Exemplo B — Pesquisa + protótipo (Pipeline)

literature-subagent raspa e resume referências (sem gravação de arquivo, acesso regulamentado à web).
prototype-subagent cria um PoC mínimo a partir do resumo.
benchmark-subagent executa microbenchmarks em uma sandbox e relata os resultados.
Essa cadeia reforça a natureza sequencial das tarefas de pesquisa, ao mesmo tempo em que mantém as responsabilidades claras.

Melhores práticas e padrões

Projeto e configuração

Comece com papéis pequenos e específicos. Torne cada subagente responsável por uma tarefa clara. Responsabilidades específicas facilitam muito a depuração.
Controle de versão do seu .claude/agents/ pasta. Trate as definições de subagentes como código — revise, teste e fixe versões. Isso reduz desvios e facilita as auditorias.
Fixe ferramentas e modelos propositalmente. Uso model: inherit Quando desejar um comportamento consistente com a conversa principal, especifique um alias de modelo de menor custo para varreduras em segundo plano. Bloqueie ferramentas para minimizar a superfície de ataque.

Padrões operacionais

Use invocação explícita para automação determinística. Se você estiver executando trabalhos ou ganchos de CI, chame subagentes específicos para garantir resultados previsíveis.
Use delegação automática em sessões interativas. Para o trabalho exploratório, deixe Claude escolher subagentes para reduzir o atrito — mas faça description campos deliberados para que a automação não seja acionada inesperadamente.
Projetar saídas estruturadas para síntese. Força subagentes a gravar em arquivos ou produzir JSON que o orquestrador possa ler; isso simplifica a etapa de redução e auditoria.

Teste, monitoramento e governança

Crie avaliações representativas. Monitore onde os subagentes falham e crie testes que exercitem esses modos de falha. A Anthropic recomenda conjuntos de testes representativos e melhorias iterativas.
Monitore o uso de tokens e ferramentas. Instrumente o uso de cada subagente e adicione alertas para detectar custos excessivos ou condições de limite de taxa.

Quando NÃO usar subagentes

Subagentes são poderosos, mas nem sempre são a ferramenta certa.

Tarefas simples: Para prompts curtos e únicos ou transformações triviais, os subagentes adicionam complexidade desnecessária.
Restrições de latência rígidas: As viagens de ida e volta de orquestração adicionam sobrecarga; se você precisar de respostas de latência extremamente baixa e de uma única volta, uma abordagem monolítica pode ser mais simples.
Equipes pequenas com pouca infraestrutura: Sem ferramentas para segredos, observabilidade e sandboxes, subagentes podem aumentar o risco operacional. Artigos da comunidade enfatizam começar pequeno e adicionar subagentes quando precisar de modularidade.

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?

Conclusão — por que os subagentes são importantes agora

Os subagentes tornam a promessa dos fluxos de trabalho agênticos prática para as equipes: eles permitem que você raciocine sobre funções, permissões, contexto, custo e paralelismo explicitamente e como objetos de primeira classe. Quando usados criteriosamente, os subagentes proporcionam maior velocidade para o desenvolvedor, melhor qualidade em tarefas com várias etapas e governança mais previsível. O outro lado é que você precisa projetar, testar e monitorar esses subagentes como se fossem um software de produção — mas esse investimento transforma engenharia ágil em prática confiável.