O que é um subagente?

Em resumo

Um subagente é um agente auxiliar que um agente de código principal inicia para delegar um trabalho específico. Ele tem a própria janela de contexto, instruções e permissões de ferramentas e, ao terminar, devolve só um resumo, para que a conversa principal não se encha de detalhes.

Como funciona

O agente principal passa um trabalho a um subagente, como buscar na base de código, rodar testes e resumir as falhas ou revisar uma mudança. O subagente começa com um contexto limpo; os arquivos que ele lê e a saída de comandos que ele vê ficam na janela dele, e o agente principal recebe só o resultado. Vários subagentes podem rodar ao mesmo tempo.

Definindo subagentes no Claude Code

No Claude Code, subagentes são arquivos Markdown com frontmatter YAML. Os subagentes do projeto ficam em .claude/agents/ e os pessoais em ~/.claude/agents/; você também pode gerenciá-los com o comando /agents.

name e description: como o subagente se chama e quando usá-lo. O agente principal decide com base nessa descrição.
tools: quais ferramentas ele pode usar, por exemplo só ferramentas de leitura para um revisor.
model: opcionalmente, um modelo diferente para o subagente.
O corpo do arquivo é o system prompt do subagente.

Quando os subagentes ajudam

Os subagentes valem mais a pena quando você quer manter a conversa principal limpa.

Pesquisa que lê muitos arquivos: os detalhes ficam no subagente e o contexto principal continua pequeno.
Papéis especializados: revisão de segurança, escrita de testes, documentação.
Exploração em paralelo: vários subagentes vasculham módulos diferentes ao mesmo tempo.

Limites

Um subagente não vê o histórico da conversa principal, então a tarefa que ele recebe precisa se sustentar sozinha. Como cada subagente monta o próprio contexto do zero, o uso total de tokens pode subir. Os subagentes costumam trabalhar na mesma pasta que o agente principal, então subagentes em paralelo que editam arquivos podem atrapalhar uns aos outros.

Subagentes no AgentVera

O AgentVera torna visíveis os subagentes que o Claude Code inicia. A visão Subagents, na janela de tour do projeto e mapa do código, lista os subagentes que um agente Claude Code iniciou.

Para cada um: tipo, se rodou em segundo plano, status, número de ferramentas e duração, além de uma linha do tempo dos seus passos.
Ela lê transcrições locais e, por enquanto, funciona com agentes Claude Code locais.
A linha de tarefas, a visão de equipe e a equipe paralela usam agentes separados e visíveis em vez de subagentes: cada um tem seu próprio painel e sua conversa, e você pode falar com ele diretamente.

Perguntas frequentes

Qual a diferença entre um subagente e uma sessão de agente separada?

O agente principal inicia um subagente e recebe o resultado de volta; normalmente você só vê o resumo. Uma sessão separada roda por conta própria e você fala com ela diretamente.

Subagentes economizam tokens?

Eles mantêm pequeno o contexto da conversa principal, o que ajuda em sessões longas. Mas a leitura do próprio subagente também custa tokens, então o uso total pode subir.

Um subagente pode editar arquivos?

Depende das ferramentas que a definição dele permite. Um subagente com apenas Read, Grep e Glob consegue ler o código, mas não alterá-lo.

Onde coloco os arquivos de subagentes?

Os que sua equipe deve compartilhar vão em .claude/agents/ no projeto; os que só você usa vão em ~/.claude/agents/. Arquivos na pasta do projeto chegam à sua equipe pelo git.