Índice
Quando você quer que vários AIs dividam o trabalho no Claude Code, existem dois mecanismos parecidos, mas diferentes — os subagents e os Agent Teams. Os nomes confundem, mas seus papéis e modos de coordenação são fundamentalmente diferentes. Este artigo esclarece o que é cada um, a diferença decisiva, qual usar e como — com base na documentação oficial.
Três pontos cruciais logo de cara. (1) Os subagents são um recurso nativo — o agente principal delega uma subtarefa focada a um "ajudante de contexto novo" e recebe de volta apenas um resumo (hierárquico, efêmero). (2) Os Agent Teams são um recurso experimental, opt-in, desativado por padrão. Eles só funcionam depois que você define CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 — múltiplas sessões independentes coordenam como pares por meio de uma lista de tarefas compartilhada (peer-to-peer, persistente). (3) "Aninhamento de 5 níveis" é um recurso dos subagents; os Agent Teams não podem aninhar (são planos) — não confunda os dois.
Hierarquia ou pares?
— delegar e receber um resumo, ou coordenar como iguais
Subagents: o agente principal entrega uma tarefa a um ajudante e recebe o resultado. Agent Teams: pares iguais coordenam por meio de uma lista de tarefas compartilhada.
Os Teams são um recurso experimental desativado por padrão — CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 é obrigatório.
1. O que são os subagents
Os subagents são agentes especializados que cuidam de tipos específicos de trabalho dentro de uma única sessão. Segundo a documentação oficial, "cada subagent roda em sua própria janela de contexto, com um system prompt personalizado e permissões de ferramentas específicas." O agente principal delega automaticamente com base no description de cada subagent, e o subagent trabalha de forma independente e retorna apenas um resumo para a conversa principal.
O ponto-chave é que "cada subagent roda em um contexto novo e separado" — ele não enxerga seu histórico de conversa nem os arquivos que você já leu. Assim, você pode fazê-lo executar buscas pesadas "do lado de fora" e receber apenas a conclusão, sem inundar seu contexto principal com logs ou saída de testes. Gerencie-os com /agents (abas Running / Library). Defina-os em .claude/agents/<name>.md com frontmatter YAML (name / description / tools / model). Entre os nativos estão o Explore (Haiku, somente leitura), o Plan e o general-purpose. Os subagents podem aninhar, até 5 níveis de profundidade (na profundidade 5 o Agent tool não é passado, então eles não podem gerar mais). Para o panorama maior, veja O que é um sistema multiagente.
2. O que são os Agent Teams (experimental, atrás de uma flag)
Os Agent Teams permitem coordenar múltiplas sessões do Claude Code como um "time." Uma delas é o team lead (coordena, atribui, sintetiza); as outras são os teammates — cada um com sua própria sessão e contexto independentes — que se comunicam diretamente entre si por meio de uma lista de tarefas compartilhada e de um mailbox. Diferentemente dos subagents, você pode conversar diretamente com cada teammate.
Importante: o Agent Teams é um recurso experimental, desativado por padrão
A documentação oficial afirma claramente que "os agent teams são experimentais e estão desativados por padrão." Para usá-los, defina a variável de ambiente CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 (ou via env do settings.json). Sem isso, nenhum time é criado na inicialização e o Claude não vai propor nem gerar teammates.
Note que a mudança da v2.1.178 apenas "removeu a etapa de configuração TeamCreate/TeamDelete, de modo que, com a flag definida, toda sessão tem um time implícito" — ela não "ativou os times por padrão." A flag continua obrigatória.
3. A diferença decisiva
Lado a lado, os dois têm formas completamente diferentes de coordenar.
| Subagents | Agent Teams | |
|---|---|---|
| Coordenação | Hierárquica (o principal delega e agrega resultados) | Peer-to-peer (autocoordenam-se por uma lista de tarefas compartilhada) |
| Comunicação | Reportam apenas ao chamador (nunca conversam entre si) | Os teammates trocam mensagens diretamente entre si pelo mailbox |
| Persistência | Efêmeros (retornam um resumo após a tarefa) | Sessões independentes persistentes (conduza-as diretamente) |
| Contexto | Contexto próprio e novo; o resumo retorna ao principal | Totalmente independentes (nada é resumido de volta automaticamente) |
| Custo de tokens | Relativamente baixo | Alto (cada teammate é uma instância separada do Claude) |
| Situação | Nativo, sempre disponível | Experimental, atrás de uma flag, desativado por padrão |
| Aninhamento | Os subagents aninham até 5 níveis | Sem aninhamento (teammates não podem gerar teammates) |
Em uma linha: Subagents = "o agente principal entrega uma tarefa focada a um ajudante de contexto novo e recebe de volta a conclusão (hierárquico, efêmero, só resumo)." Agent Teams = "múltiplas sessões persistentes coordenam por meio de uma lista de tarefas compartilhada e de mensagens, e você pode conduzir cada uma (pares, independentes)." Um erro comum: "aninhamento de 5 níveis" é um recurso dos subagents, enquanto os Teams são planos (sem aninhamento).
4. Qual deles você deve usar
Escolha pelo propósito e você não vai sofrer. A maior parte do trabalho do dia a dia fica bem com subagents (ou com uma única sessão).
Escolha pelo propósito
· o trabalho é autocontido e só o resultado importa
· você quer limitar ferramentas ou um modelo mais barato
· os workers não precisam conversar
· a exploração paralela compensa (revisão paralela / debug de hipóteses concorrentes / multimódulo)
· você quer conduzir cada worker
(aceite o custo maior + a flag)
· você precisa de muita troca de ida e volta
· ela mexe nos mesmos arquivos
· é uma alteração local rápida
Por padrão, prefira "na dúvida, uma única sessão ou subagents."
Recorra aos Agent Teams apenas para trabalho paralelo que realmente precise de coordenação entre pares.
5. Guia rápido de uso
Uma referência rápida para comandos e configuração.
# --- Subagents (nativo) ---
/agents # gerenciador (Running / Library)
.claude/agents/<name>.md # definição do projeto (name/description/tools/model)
~/.claude/agents/<name>.md # definição do usuário (todos os projetos)
claude --agent code-reviewer # roda a sessão inteira como um subagent específico
@agent-<name> # @-menção para invocar explicitamente
# --- Agent Teams (experimental, atrás de uma flag) ---
# Ative via env (ou env do settings.json); DESATIVADO por padrão
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
# Depois descreva em linguagem natural, ex.: "Crie três teammates para revisar a PR #142:
# um para segurança, um para desempenho, um para cobertura de testes."
# Exibição via teammateMode (padrão in-process; painéis divididos precisam de tmux/iTerm2)No arquivo de definição de um subagent, você pode restringir ferramentas com tools ou direcionar para um modelo mais leve como o haiku com model. Para construir e projetar agentes, veja Como construir um sistema multiagente e Como construir um agente de IA.
6. Cuidados com os Agent Teams
Os Agent Teams são poderosos, mas trazem limites e custos próprios da fase experimental. Conheça-os antes de adotá-los.
(1) Um time por sessão, sem aninhamento — teammates não podem gerar teammates, e o lead é fixo. (2) Uso alto de tokens (cada teammate é uma instância separada do Claude); a recomendação é de 3 a 5 teammates. (3) Os teammates não são isolados em worktrees, então, se mexerem nos mesmos arquivos, sobrescrevem uns aos outros — particione os arquivos manualmente. (4) Por ser um recurso experimental, há limites como /resume e /rewind não restaurarem teammates in-process. (5) A exibição em painéis divididos precisa de tmux ou iTerm2 (alguns terminais, como o do VS Code, não são suportados). Em resumo, use-os apenas quando o retorno da coordenação paralela superar o custo e o esforço.
Resumo
Os subagents e os Agent Teams do Claude Code ambos "dividem o trabalho entre AIs," mas seus modelos de coordenação diferem. Os subagents são nativos — o agente principal delega uma tarefa focada a um ajudante de contexto novo e recebe de volta apenas um resumo (hierárquicos, efêmeros, não conversam entre si, aninham até 5 níveis). Os Agent Teams são um opt-in experimental, desativado por padrão (precisa de CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1) — múltiplas sessões independentes coordenam como pares por meio de uma lista de tarefas compartilhada e de mensagens (persistentes, conduza cada uma, sem aninhamento).
Como escolher: "quer só o resultado / não quer poluir o contexto → subagents," "trabalho paralelo em que os workers precisam compartilhar e coordenar → Agent Teams," "sequencial / mesmos arquivos / correção rápida → uma única sessão." Uma confusão comum: "aninhamento de 5 níveis" é um recurso dos subagents; os Teams são planos. E note que a v2.1.178 simplificou a inicialização dos times — ela não "ativou por padrão." Os Teams são caros e experimentais, então limite-os aos casos em que a coordenação compensa. Relacionados: O que é um sistema multiagente, como construir um, Observabilidade de IA.
FAQ
Q. Em que os subagents e os Agent Teams diferem?
A. A coordenação deles é fundamentalmente diferente. Os subagents são hierárquicos — o agente principal delega uma tarefa focada a um ajudante de contexto novo e recebe de volta apenas um resumo (os ajudantes não conversam entre si; efêmeros). Os Agent Teams são peer-to-peer — múltiplas sessões independentes coordenam por meio de uma lista de tarefas compartilhada e de um mailbox, e você pode conduzir cada uma (persistentes). Os subagents são nativos; os Agent Teams são experimentais e exigem uma flag.
Q. Posso usar os Agent Teams de imediato?
A. Não — eles estão desativados por padrão. Você precisa definir CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 no env (ou no env do settings.json). A v2.1.178 apenas simplificou a inicialização (ela "removeu a etapa de configuração TeamCreate, de modo que, com a flag definida, toda sessão tem um time implícito") — ela não "ativou os times por padrão." A flag continua obrigatória.
Q. A qual deles se refere "aninha até 5 níveis"?
A. Aos subagents. Um subagent pode gerar seus próprios subagents, até 5 níveis de profundidade (na profundidade 5 ele não pode ir além). Os Agent Teams não podem aninhar — teammates não podem gerar teammates, e só o lead gerencia o time. Não confunda os dois.
Q. Não consigo decidir qual usar.
A. Na maioria das vezes, uma única sessão ou subagents bastam. Se você quer só o resultado e não quer que uma saída pesada inunde seu contexto principal, use subagents. Se os workers precisam compartilhar achados, conferir uns aos outros e autocoordenar-se em trabalho paralelo (revisão paralela, debug de hipóteses concorrentes, desenvolvimento multimódulo) e você quer conduzir cada um, use Agent Teams. Para trabalho sequencial, muita troca de ida e volta ou mexer nos mesmos arquivos, uma única sessão se encaixa.
Q. Com o que devo me preocupar nos Agent Teams?
A. Uso alto de tokens (cada teammate é uma instância separada; 3 a 5 recomendados), um time por sessão sem aninhamento, teammates não isolados em worktrees, então conflitam nos mesmos arquivos (particione manualmente), limites experimentais em /resume e /rewind, e painéis divididos que precisam de tmux/iTerm2. Use-os apenas para trabalho paralelo em que a coordenação supera o custo.
