Í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, iniciado por tarefa). (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) Só os subagents podem aninhar (por padrão, até 3 camadas abaixo da conversa principal); 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. Para criá-los ou editá-los, peça ao Claude ou edite o arquivo de definição diretamente (desde a v2.1.198, o /agents não abre mais o assistente interativo de criação). Defina-os em .claude/agents/<name>.md com frontmatter YAML (name / description / tools / model). Entre os nativos estão o Explore (somente leitura; desde a v2.1.198 herda o modelo da conversa principal, com teto no Opus na Claude API), o Plan e o general-purpose. Os subagents podem aninhar, por padrão até 3 camadas abaixo da conversa principal (v2.1.219+; no limite de profundidade o Agent tool não é passado, então eles não podem gerar mais. O limite é alterado com CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH; com 1 o aninhamento é desativado). 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 | Sobretudo retornam um resultado ao chamador (subagents nomeados também podem trocar mensagens entre si) | Os teammates trocam mensagens diretamente entre si pelo mailbox |
| Persistência | Iniciados por tarefa (retornam um resumo; podem ser retomados) | 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 | Por padrão até 3 camadas abaixo (limite ajustável) | 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, um por tarefa, 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: o aninhamento é 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 # sem assistente desde a v2.1.198 (peça ao Claude ou edite os arquivos abaixo)
.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. Como o modelo é definido e um teste real com outros modelos estão em Claude Code: como rodar subagentes em outro modelo. 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, um por tarefa, reportam sobretudo ao chamador, aninham por padrão até 3 camadas). 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: o aninhamento é 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. Vale notar que os dois que comparamos aqui rodam na sua própria máquina. Como opção na nuvem, que segue andando depois que você fecha o terminal, o Projects chegou em setembro de 2026 — nele o próprio Claude abre as threads e acompanha cada uma. 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 reportam sobretudo ao chamador, mas os nomeados podem trocar mensagens entre si; iniciados por tarefa e retomáveis). 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. Qual dos dois pode aninhar?
A. Os subagents. Um subagent pode gerar seus próprios subagents, por padrão até 3 camadas abaixo da conversa principal (v2.1.219+; o limite é alterado com CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH, e com 1 o aninhamento é desativado). 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. Existem formas de paralelizar além dessas duas?
A. Existem. A documentação oficial organiza a paralelização em cinco abordagens: além das duas deste artigo, há o agent view (dispatch), os fluxos de trabalho dinâmicos e o Projects, que entrou em setembro de 2026. O agent view é a tela que você abre com claude agents, na qual você entrega tarefas independentes e recolhe os resultados depois (research preview). Os subagents significam "o Claude delega dentro de uma conversa" e os Agent Teams significam "o Claude conduz o trabalho", enquanto no agent view quem conduz é você. O modelo de isolamento e os pontos de atenção estão em um artigo dedicado.
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.
