Claude Code Agent Teams: Guia Multissessão (2026)

- Este é um recurso em research preview, e a mecânica de ativação já mudou uma vez (antes/depois da v2.1.178 - as ferramentas manuais de criar time não existem mais). Os detalhes aqui foram checados contra a documentação oficial no momento em que escrevi (08/2026) - confira a documentação ao vivo antes de depender disso.

O que as agent teams realmente são

Agent teams é um recurso em research preview do Claude Code que deixa várias sessões rodarem em paralelo dentro de um "time": um agente lead coordena, e um ou mais teammates executam tarefas. Cada teammate ganha sua própria janela de contexto - ele não compartilha contexto com o lead nem com os outros teammates - e o time inteiro compartilha uma lista de tarefas mais um canal de mensagens diretas (mailbox). Segundo a documentação oficial em code.claude.com/docs/en/agent-teams (checada em 08/2026), isso é uma camada de coordenação em cima de sessões independentes do Claude Code - não um novo modelo, não uma API separada.

Uma linha para evitar confusão: agent teams não são as personas "advisor" ou "kongming" do AgentKit - elas funcionam de um jeito bem diferente (veja a leitura honesta no final).

Agent teams vs subagents

Se você já se sente à vontade com Claude Code subagents, aqui está a comparação direta da documentação (resumida):

Versão curta: um subagent é "delegue o trabalho e receba um resultado de volta"; agent teams é "um grupo trabalhando junto e trocando mensagens diretamente". Para escalar ainda mais a orquestração de subagents, veja orquestrando subagents em escala.

Quem detém o plano: subagents vs skills vs agent teams vs workflows

Este é o principal ganho de informação do artigo - uma comparação de 4 vias tirada direto da documentação do Claude Code (code.claude.com/docs/en/workflows, checada em 08/2026) que nenhum dos concorrentes que verificamos, EN ou VI, reproduz por completo:

Nenhum dos artigos concorrentes que verificamos reproduz esse enquadramento exato de 4 vias - a maioria só compara agent teams com subagents e pula skills e workflows por completo. Para um mergulho fundo em workflows/ultracode, veja Claude Code Dynamic Workflows.

Habilitando as agent teams - CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

As agent teams vêm desativadas por padrão. Ligue com uma variável de ambiente no settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "true"
  }
}

Algumas coisas que vale lembrar (segundo a documentação, checada em 08/2026 - confira na versão do Claude Code que você realmente está rodando antes de depender disso):

• Só funciona numa sessão interativa - não roda via -p nem pelo Agent SDK.
• Na configuração atual (pós-v2.1.178), você não precisa chamar manualmente as ferramentas TeamCreate/TeamDelete como alguns textos mais antigos descrevem - essas ferramentas não existem mais no fluxo atual. Se você ler um guia descrevendo um passo manual de criar time, ele provavelmente foi escrito antes dessa mudança - um exemplo concreto do aviso de "pode mudar" que a própria Anthropic dá.

Começando seu primeiro time e a lista de tarefas compartilhada

Uma vez habilitado, comece com uma tarefa grande o bastante para dividir entre perspectivas, por exemplo:

Spawn a team of 3 teammates to review this PR:
one for security, one for performance, one for test coverage.
Report findings back to me.

O Claude Code cria uma lista de tarefas compartilhada para o time inteiro, com estados familiares: pending, in progress, completed. Alguns mecanismos que vale conhecer:

• Bloqueio por dependência - uma tarefa pode esperar outra terminar antes de começar.
• Auto-atribuição ou atribuída pelo lead - um teammate pode pegar sozinho uma tarefa pendente, ou o lead pode atribuí-la diretamente.
• Trava de arquivo ao pegar - quando um teammate pega uma tarefa que mexe num arquivo específico, uma trava impede que dois teammates editem o mesmo trecho ao mesmo tempo.

Cross-session messaging - um recurso diferente, não um time

É aqui que a maioria dos concorrentes (EN e VI) embaralha a linha, tratando como "mensagens do time". A documentação na verdade trata como um recurso separado: o cross-session messaging deixa duas sessões independentes do Claude Code - mesmo em outra máquina, ou via Remote Control - passarem mensagens por ListAgents/SendMessage (ou o comando /list-agents), sem que as duas pertençam ao mesmo time supervisionado pelo Claude.

Quando usar cada um: se você quer que o próprio Claude coordene um grupo por uma lista de tarefas compartilhada, use agent teams. Se você tem algumas sessões independentes que está guiando você mesma e só precisa que elas troquem mensagens quando pedir, o cross-session messaging é a ferramenta certa e mais leve - você não precisa ligar todo o mecanismo de time para isso.

Nota de plataforma: o cross-session messaging atualmente só roda em macOS/Linux - ainda não há suporte nativo no Windows. O WSL2 conta como Linux, então lá funciona. O modo de exibição em painel dividido do time também precisa de tmux ou iTerm2, e explicitamente não funciona no Windows Terminal. Não vi um único concorrente (EN ou VI) mencionar isso - vale destacar, dado quantas máquinas de dev entre os leitores deste site rodam Windows.

Agent view - o painel para sessões paralelas em segundo plano

Um recurso relacionado e fácil de confundir: o agent view, aberto com claude agents. É um painel que lista suas sessões paralelas em segundo plano - diferente das agent teams, não há mensagens entre sessões, é puramente uma tela de monitoramento. Também é research preview.

Vale corrigir uma confusão bem comum: o isolamento por um git worktree dedicado por sessão é o mecanismo do agent view (para sessões em segundo plano), não um comportamento padrão das agent teams. Alguns textos descrevem as agent teams como se criassem automaticamente um worktree separado por teammate, apresentado como uma espécie de "universo paralelo" - a documentação de Arquitetura das agent teams não descreve mecanismo nenhum desse tipo; ela só descreve lead/teammate/lista de tarefas/mailbox, sem qualquer menção a worktrees automáticos.

Um caso de uso realista: PR review em paralelo

O caso de uso mais forte na documentação oficial (e o que eu de fato escolheria) é um PR review em paralelo: subir 3 teammates, cada um lendo o mesmo PR por uma lente diferente - segurança, performance, cobertura de testes - e depois reportando de volta para você. Como cada teammate tem seu próprio contexto, eles não atrapalham uns aos outros ao ler o mesmo diff.

Sendo honesta: este passo a passo é modelado no caso de uso documentado pela própria Anthropic, não em uma execução de primeira mão com números específicos (quantidade de problemas, de PRs). Se você vir outra review citando números precisos como "X problemas encontrados em Y minutos", vale perguntar se de fato rodaram ou só estão parafraseando a documentação. Outro padrão que vale tentar: dê um bug difícil a vários teammates trabalhando hipóteses concorrentes, e deixe o lead sintetizar qual hipótese encaixa melhor nas evidências.

Qualquer um dos padrões só compensa quando as subtarefas realmente se beneficiam de contexto separado - ler o mesmo diff por lentes diferentes, ou perseguir teorias diferentes de causa raiz sem que a suposição de um teammate contamine a de outro. Para trabalho que é quase todo sequencial (implementar, depois testar, depois documentar) uma simples cadeia de subagents costuma ser mais barata e fácil de raciocinar do que montar um time inteiro.

Limitações - o que ainda não funciona

Como isto é um research preview, a documentação lista abertamente as próprias limitações atuais - vale ler antes de apostar um fluxo importante nesse recurso:

• Sem retomada para teammates em andamento depois de fechar o terminal - fechar a sessão perde aquele teammate.
• O status das tarefas atrasa - a lista de tarefas nem sempre reflete o que um teammate está fazendo em tempo real.
• Um time por sessão - você não pode rodar vários times em paralelo sob uma sessão lead.
• Sem times aninhados - um teammate não pode subir seu próprio subtime.
• Painéis divididos precisam de tmux/iTerm2 e não funcionam no Windows Terminal (mesma ressalva do cross-session messaging).

É também por isso que o artigo insiste em "research preview": a mecânica de ativação já mudou uma vez (removendo o passo manual da ferramenta de criar time), então esta lista de limitações é uma boa candidata a mudar também. Não trave um fluxo crítico de produção nos detalhes/comportamento exatos descritos aqui sem checar de novo.

Ângulo honesto sobre o AgentKit: as personas dele podem ser teammates?

A pergunta direta: as personas advisor e kongming do AgentKit podem agir como teammates em uma agent team? Não, não como um teammate persistente.

• O kongming é one-shot: um prompt entra, uma resposta sai, sem turnos de ida e volta.
• O advisor é de entrevista em revezamento: ele faz perguntas uma de cada vez e volta à sessão principal entre elas - não é uma sessão independente rodando em paralelo, trocando mensagens por um mailbox.

Nenhum foi feito para as mensagens persistentes e de múltiplos turnos que um teammate precisa (segundo docs.agentkit.best/en/beta/concepts/advisory-supervision, checado em 08/2026).

Mas há uma nuance real que vale dizer com todas as letras em vez de passar por cima: o Claude Code deixa você subir um teammate usando qualquer tipo de agente definido no nível de projeto/usuário/plugin - e o adaptador de runtime do AgentKit instala os agentes do kit como definições nativas de subagent do Claude Code. Então, tecnicamente, um agente de execução de tarefas de um kit AgentKit (não o advisor/kongming) pode ser indicado como teammate. Isso não é a mesma coisa que "o AgentKit já vem com times prontos" - vou dizer o limite com clareza: o AgentKit é um kit pago que te dá personas/skills para delegar trabalho; agent teams é o mecanismo de coordenação gratuito do Claude Code em que você mesma pluga essas personas - não um produto "time" empacotado pelo AgentKit. Veja a review completa do AgentKit para mais.

Perguntas frequentes (FAQ)

O que o CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS faz?

É uma variável de ambiente (definida no settings.json) que habilita o recurso de agent teams do Claude Code, desativado por padrão por ainda ser um research preview. Só funciona numa sessão interativa, não via -p nem pelo Agent SDK.

Em que as agent teams diferem dos subagents?

Um subagent roda dentro do contexto da sessão que o chamou, pega uma tarefa e devolve um resultado, sem troca de mensagens de ida e volta. Agent teams envolvem várias sessões independentes (cada teammate com seu próprio contexto), compartilhando uma lista de tarefas e trocando mensagens diretamente por um mailbox enquanto rodam - com custo de tokens bem mais alto.

O cross-session messaging funciona no Windows?

Ainda não nativamente - por enquanto só roda em macOS/Linux. O WSL2 conta como Linux, então lá funciona. O modo de exibição em painel dividido do time também precisa de tmux ou iTerm2, e não funciona no Windows Terminal.

Qual o custo de tokens de um time em comparação a uma única sessão?

Bem mais alto, porque cada teammate é uma sessão inteira rodando em paralelo, sem contexto compartilhado com a sessão principal. A documentação não dá um número fixo - só recorra a isso quando você realmente precisar de perspectivas paralelas, não quando um único agente trabalhando de forma sequencial já resolveria.

Posso retomar um time depois de fechar o terminal?

Ainda não. Segundo as limitações atuais, teammates em andamento não conseguem retomar depois que você fecha a sessão - fechar o terminal perde aquele teammate. Esta é uma das limitações que a própria documentação lista abertamente.

Esse recurso é estável o suficiente para o trabalho diário?

Nem tanto - ainda é um research preview, e a mecânica de ativação já mudou uma vez (removendo o passo manual da ferramenta de criar time). Tudo bem experimentar em exploração paralela não crítica; ainda não é algo em que se apoiar para um fluxo diário obrigatório, dada a estabilidade que ainda falta.

Conclusão

Agent teams ainda é um research preview - forte para exploração em paralelo (várias perspectivas sobre um problema ao mesmo tempo), não um substituto do trabalho sequencial mais simples que um subagent ou skill já dá conta. Mantenha a tabela de 4 vias "quem detém o plano" como seu atalho de decisão: um único agente seguindo instruções sequenciais - subagent/skill; sessões longas e colaborativas que trocam mensagens entre si - agent teams; trabalho maior que uma janela de contexto ou que precisa de centenas de subagents - workflow. Experimente primeiro em algo não crítico, leia as limitações com atenção e não trave um processo de produção em detalhes que podem mudar a qualquer momento.