Subagentes e equipes de agentes no Claude Code: o que são e quando usar cada um

Resposta curta: um subagente é um assistente que o Claude Code chama para fazer uma parte do trabalho num contexto separado e devolver só o resultado. Uma equipe de agentes reúne várias sessões completas do Claude Code trabalhando ao mesmo tempo e trocando mensagens entre si. A seguir, como cada um funciona, quanto custa e quando vale usar.

Quem usa o Claude Code para além de programar, em pesquisa, redação, análise de campanha ou revisão de marca, logo encontra dois termos na documentação da Anthropic: subagentes e equipes de agentes, chamadas de agent teams. Os dois dividem o trabalho entre várias instâncias de IA e por isso parecem a mesma coisa. Eles resolvem problemas diferentes e custam diferente.

Na Headcore usamos subagentes todos os dias. A operação de marca roda hoje com 17 deles, organizados em seis plugins, do diagnóstico de marca à análise de mídia. Este guia explica os dois recursos com base na documentação oficial do Claude Code, consultada em outubro de 2026, e no que aprendemos montando esses agentes.

Se o conceito de agente ainda é novo para você, vale começar pelo nosso texto sobre IA agêntica e agentes de IA.

O que é um subagente

Um subagente é um assistente especializado que o Claude Code chama para fazer uma parte do trabalho. Ele tem instruções próprias, uma lista própria de ferramentas que pode usar e uma janela de contexto separada da conversa principal. Esse último ponto é a razão de ele existir.

Janela de contexto é tudo o que o modelo considera ao mesmo tempo: a conversa, os arquivos lidos, os resultados de busca. Ela tem limite, e quanto mais cheia, mais o modelo se distrai com o que já não importa. Como mostramos em como usar IA em marca, boa parte da qualidade da resposta depende do que está nessa janela.

Um exemplo: você pede ao Claude Code uma leitura de 40 relatórios de campanha. Se a conversa principal lê os 40, ela termina lotada de números que não vai usar de novo. Com um subagente, a leitura acontece em outro contexto, e a conversa principal recebe só a conclusão, em poucas linhas.

O que o subagente recebe e o que ele devolve

Dois detalhes explicam a maioria dos tropeços de quem começa. O subagente não vê a sua conversa. Ele recebe o pedido que o Claude escreve ao chamá-lo, as instruções do próprio arquivo e o contexto do projeto. Se uma decisão foi tomada dez mensagens atrás, ela precisa estar escrita no pedido, ou o subagente vai trabalhar sem ela.

Do outro lado, só o resultado final volta. As buscas, leituras e tentativas ficam no contexto do subagente. Isso poupa espaço na conversa principal, que passa a confiar no resumo. Quando o resumo vem errado, o caminho que levou ao erro não aparece na conversa, e só quem abre o registro do subagente consegue ver onde ele se perdeu.

Normalmente, os subagentes que a conversa principal cria rodam em segundo plano. Você continua trabalhando enquanto eles leem e buscam, e o resultado chega como uma notificação quando terminam. Pesquisas independentes podem rodar em paralelo, cada uma no seu subagente.

Como criar um subagente

Um subagente é um arquivo de texto em Markdown, com um cabeçalho de configuração e as instruções logo abaixo. O Claude Code procura esses arquivos na pasta .claude/agents/ do projeto, para agentes que só fazem sentido ali, e em ~/.claude/agents/, para os que você quer em todos os projetos. Plugins também podem trazer os seus.

Só dois campos são obrigatórios, name e description. Um exemplo pensado para quem cuida de conteúdo:

---
name: revisor-de-voz
description: Revisa textos de blog, legenda e e-mail contra o guia de voz da marca. Use antes de publicar qualquer texto.
tools: Read, Grep, Glob
model: sonnet
---

Você revisa textos da marca. Leia o guia de voz em docs/voz.md antes de começar.
Aponte cada trecho que foge do guia, diga qual regra ele quebra e sugira uma
versão nova para o trecho. Não reescreva o texto inteiro e não altere arquivos.

O campo que mais pesa é a description. É lendo essa frase que o Claude decide se vale delegar e para quem. Uma descrição vaga, como “ajuda com textos”, faz o agente ser chamado na hora errada, ou nunca. A que funciona diz o que ele faz e em que momento deve entrar.

O campo tools limita as ferramentas. No exemplo, o revisor só lê e busca, então não tem como editar um arquivo por engano. O campo model escolhe o modelo, e tarefas simples podem ir para um modelo mais barato. Um cuidado: o Claude Code ignora sem aviso um campo com a grafia errada, então vale conferir letra por letra.

Para usar, basta pedir em linguagem comum (“use o revisor-de-voz neste post”) ou mencionar o agente com @. O Claude também chama o subagente sozinho quando a tarefa combina com a descrição. Quem não quer escrever o arquivo pode pedir ao próprio Claude Code que o crie.

O Claude Code já vem com alguns subagentes prontos. O Explore só lê e serve para buscar em muitos arquivos sem gastar o contexto principal. O Plan é usado no modo de planejamento, para levantar informação antes de propor um plano. Há também um de uso geral, para tarefas que exigem ler e agir.

O que são as equipes de agentes

As equipes de agentes levam a ideia mais longe. Em vez de um ajudante que faz a tarefa e devolve o resultado, você tem várias sessões completas do Claude Code trabalhando ao mesmo tempo. Uma delas é a líder, que divide o trabalho, distribui as tarefas e junta o que volta. As outras são as colegas de equipe.

O que muda é a comunicação. Subagentes só falam com quem os chamou. Numa equipe, as colegas trocam mensagens diretamente e trabalham sobre uma lista de tarefas compartilhada, em que cada uma pega a próxima tarefa livre quando termina a sua. Você também pode falar com qualquer colega sem passar pela líder.

O recurso ainda é experimental e vem desligado. Para ativar, defina a variável CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS com o valor 1, no ambiente do terminal ou no arquivo settings.json. Depois disso, descreva a tarefa e peça a equipe em linguagem comum. As colegas aparecem num painel abaixo do campo de texto, e dá para abrir cada uma.

Um pedido que funciona bem, adaptado de um exemplo da própria documentação para marketing: “Crie uma equipe de três colegas para revisar esta landing page. Uma olha a clareza da oferta, outra olha SEO e a terceira faz o papel de um cliente desconfiado. Peça que discutam entre si antes de me entregar a conclusão.”

Subagentes ou equipe de agentes: qual a diferença

Fonte: documentação do Claude Code, outubro de 2026.

Um jeito curto de decidir: se os agentes não precisam conversar entre si, use subagentes. Se precisam discutir, contestar o achado do outro ou dividir um trabalho grande com dependências entre as partes, a equipe começa a valer o custo.

Quando vale a pena usar, e quando não

Os dois recursos gastam mais tokens que uma conversa única. Cada subagente consome tokens enquanto trabalha, e esse consumo conta no mesmo limite de uso da conversa principal. Numa equipe, o gasto cresce com o número de colegas. Para corrigir um texto, ajustar uma página ou tirar uma dúvida, um agente só resolve mais rápido e por menos.

Subagentes compensam quando a tarefa gera muito material intermediário e pouco resultado, como ler dezenas de arquivos, varrer uma pasta ou checar uma lista de URLs. Também compensam quando você quer a mesma tarefa feita sempre do mesmo jeito, com as mesmas regras e as mesmas ferramentas.

Para equipes, a documentação recomenda começar com três a cinco colegas e observa que três focadas costumam render mais que cinco dispersas. Sugere também começar por pesquisa e revisão, que não exigem editar arquivos. Duas colegas editando o mesmo arquivo sobrescrevem o trabalho uma da outra.

As limitações conhecidas pedem alguém acompanhando. Cada sessão comporta uma equipe só, e as colegas não montam equipes próprias. Ao retomar uma sessão, as colegas não voltam junto. O status das tarefas às vezes atrasa, e a líder pode dar o trabalho por encerrado antes da hora.

Como usamos subagentes na Headcore

Nossa operação de marca roda no Growth System™, o conjunto de seis plugins do Claude Code que montamos, com 17 subagentes ao todo. Cada plugin cuida de uma etapa: construir o Brand Brain da marca, escrever e compor peças, desenhar páginas, produzir vídeo, analisar mídia e julgar o trabalho antes da entrega. O Brand Brain guarda posicionamento, voz, regras visuais e decisões, e os agentes leem dali antes de produzir.

Três escolhas de desenho ajudaram mais do que esperávamos. A primeira foi dar a cada agente uma pergunta só. O redator escreve e não decide formato nem visual. O diretor de arte define o tratamento da peça e não a executa. Com uma função por agente, a descrição fica clara e o Claude acerta a quem delegar.

A segunda foi usar o contexto separado a favor da análise. No plugin de mídia, o analista e a checagem rodam em paralelo. O analista diz o que mudou nos números e por quê; a checagem confere se a operação fez o que a estratégia previa. Como um não lê o parecer do outro, nenhum puxa o colega para a própria conclusão.

A terceira foi limitar ferramentas. Os agentes que só analisam têm acesso de leitura, sem permissão para editar arquivos, o que elimina uma classe inteira de acidentes. O revisor do exemplo acima segue a mesma lógica e confere textos contra regras como as do nosso mapa de padrões de texto de IA.

Também erramos. Às vezes um agente responde de memória quando devia consultar a fonte. Por isso nenhuma peça sai sem revisão humana, e cada regra nova vai para o Brand Brain, para que o mesmo erro não volte na marca seguinte. Ainda não medimos quanto tempo esse desenho economiza, e essa conta continua em aberto.

Por onde começar

Comece com um subagente para uma tarefa que você repete toda semana e que exige muita leitura: revisar textos contra o guia de voz, conferir os links de uma página, resumir relatórios. Escreva a descrição pensando no momento em que ele deve ser chamado, deixe só as ferramentas de que ele precisa e teste num caso real antes de confiar.

Com dois ou três subagentes funcionando, vale testar uma equipe num trabalho de revisão, com três colegas olhando a mesma peça por ângulos diferentes. Acompanhe o que cada uma faz e pare quando a sua revisão virar o gargalo. Se tudo que a equipe entrega precisa ser refeito, revise as instruções antes de pensar em mais agentes.

A série completa

Este texto faz parte de uma série de cinco sobre agentes de IA aplicados a marca:

1. Subagentes e equipes de agentes no Claude Code (este texto)
2. Skills e plugins no Claude Code
3. CLAUDE.md e Brand Brain: memória de marca para IA
4. Como revisar conteúdo gerado por IA
5. Como usamos IA na operação da Headcore

Perguntas frequentes

Fontes: documentação do Claude Code sobre subagentes e sobre equipes de agentes, consultadas em 21/10/2026.