Agent Teams - Orquestração de equipes de sessão do Claude Code

 (code.claude.com)
29 pontos por GN⁺ 2026-02-06 | 2 comentários | Compartilhar no WhatsApp
  • Recurso experimental que organiza várias instâncias do Claude Code em uma única equipe para distribuir e coordenar trabalho em paralelo, com a sessão líder criando colegas de equipe, atribuindo tarefas e consolidando os resultados
  • Diferente dos subagentes existentes, permite troca direta de mensagens entre os membros da equipe, e o usuário também pode se comunicar diretamente com membros individuais sem passar pelo líder
  • É eficaz para revisão de código, exploração paralela de hipóteses de depuração e trabalho entre camadas, como frontend, backend e testes; para trabalho sequencial ou edição do mesmo arquivo, uma única sessão é mais adequada
  • Como cada membro da equipe tem sua própria janela de contexto independente, o uso de tokens aumenta bastante, e o custo pode crescer proporcionalmente ao número de membros
  • Oferece suporte ao modo de tela dividida com tmux ou iTerm2 e ajuda a aumentar a produtividade e a qualidade de tarefas complexas de desenvolvimento por meio de exploração paralela e automação da colaboração

Visão geral do Agent Teams

  • Coordena várias sessões do Claude Code como uma única equipe para executar trabalho em paralelo
    • O líder da equipe distribui tarefas e consolida os resultados
    • Cada membro executa individualmente em sua própria janela de contexto independente
  • Diferente de Subagent, permite mensagens diretas entre os membros da equipe
  • É um recurso experimental e vem desativado por padrão; pode ser ativado definindo a variável de ambiente CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

Quando vale a pena usar Agent Teams

  • Pesquisa e revisão: vários membros investigam simultaneamente diferentes aspectos do problema, depois compartilham os resultados e fazem validação cruzada
  • Desenvolvimento de novos módulos ou funcionalidades: cada membro assume um arquivo/módulo separado para trabalhar em paralelo sem conflitos
  • Depuração com hipóteses concorrentes: testa hipóteses diferentes ao mesmo tempo para identificar a causa mais rapidamente
  • Coordenação entre camadas: distribui membros por camada, como frontend, backend e testes, para mudanças simultâneas
  • Para trabalho sequencial, edição do mesmo arquivo ou tarefas com muitas dependências, uma sessão única ou subagentes são mais eficientes

Subagent vs. Agent Team

  • Subagente: tem sua própria janela de contexto, mas retorna resultados apenas ao chamador; o agente principal gerencia todo o trabalho; o custo de tokens é relativamente menor
  • Equipe de agentes: janelas de contexto totalmente independentes, possibilidade de trocar mensagens diretas entre membros, auto-organização com lista de tarefas compartilhada; como cada membro é uma instância separada do Claude, o custo de tokens é maior
  • Para trabalho focado em que só o resultado final importa, subagentes são mais adequados; para tarefas complexas que exigem discussão e colaboração entre membros, Agent Teams é a melhor escolha

Como iniciar sua primeira equipe de agentes

  • Por padrão, o recurso vem desativado; ative-o definindo a variável de ambiente CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS como 1 ou adicionando essa variável ao settings.json
  • Depois de ativado, basta descrever em linguagem natural a estrutura da equipe e o trabalho para que o Claude crie a equipe, gere os membros e coordene a execução
    • > I'm designing a CLI tool that helps developers track TODO comments across their codebase. Create an agent team to explore this from different angles: one teammate on UX, one on technical architecture, one playing devil's advocate.
    • Estou projetando uma ferramenta CLI para rastrear comentários TODO em uma base de código; faça três membros explorarem isso de forma independente — um focado em UX, um em arquitetura técnica e um no papel de contraponto — e depois consolide os resultados
    • Assim, o Claude tentará criar uma lista de tarefas compartilhada, gerar cada membro da equipe, explorar cada problema, consolidar os resultados e encerrar a equipe quando o trabalho terminar
  • O terminal do líder mostra a lista completa dos membros e o status das tarefas, e você pode selecionar um membro com Shift+Up/Down para enviar mensagens diretamente

Controle da equipe de agentes

  • Escolha do modo de exibição

    • Modo in-process: todos os membros executam dentro do terminal principal; selecione um membro com Shift+Up/Down e envie mensagens; não requer configuração adicional
    • Modo split panes: cada membro aparece em um painel separado, permitindo acompanhar a saída simultaneamente; requer tmux ou iTerm2
    • O padrão "auto" usa split pane se estiver rodando dentro de uma sessão tmux; caso contrário, usa in-process
    • A configuração "tmux" ativa o modo split-pane e detecta automaticamente tmux e iTerm2
    • É possível sobrescrever com teammateMode no settings.json ou usar a flag claude --teammate-mode in-process para forçar sessão única

  • Definição de membros e modelo

    • O Claude decide automaticamente o número de membros conforme a tarefa, mas é possível informar diretamente a quantidade exata e o modelo (por exemplo, Sonnet) com comandos como "Create a team with 4 teammates"

  • Exigir aprovação de plano

    • Em tarefas complexas ou arriscadas, é possível aplicar aos membros o modo de plano somente leitura, bloqueando a implementação até que o líder aprove
    • Quando um membro conclui o plano, envia um pedido de aprovação ao líder; se aprovado, inicia a implementação; se recusado, incorpora o feedback e reenviá
    • Os critérios de decisão do líder podem ser influenciados por condições dadas no prompt (por exemplo, "Approve only plans that include test coverage")

  • Modo de delegação (Delegate)

    • Em vez de implementar diretamente, o líder fica restrito a usar apenas ferramentas de coordenação (gerar membros, enviar mensagens, encerrar, gerenciar tarefas)
    • Depois de iniciar a equipe, pressione Shift+Tab para alternar para o modo de delegação

  • Conversa direta com os membros

    • Como cada membro é uma sessão totalmente independente do Claude Code, é possível enviar diretamente instruções adicionais, perguntas de acompanhamento e mudanças de abordagem
    • No modo in-process, selecione com Shift+Up/Down e envie mensagens; Enter para verificar a sessão, Escape para interromper o turno atual e Ctrl+T para alternar a lista de tarefas
    • No modo split-pane, clique no painel correspondente para interagir diretamente

  • Atribuição e claim de tarefas

    • A equipe coordena o trabalho por meio de uma lista de tarefas compartilhada, com três estados: pending, in progress e completed
    • É possível definir dependências entre tarefas, e tarefas com dependências não resolvidas não podem ser assumidas
    • O líder pode atribuir explicitamente uma tarefa, ou o membro, ao concluir uma atividade, pode assumir automaticamente a próxima tarefa não atribuída e não bloqueada
    • Usa bloqueio de arquivo para evitar que vários membros assumam a mesma tarefa ao mesmo tempo

  • Encerrar membros e limpar a equipe

    • Se o líder solicitar o encerramento de um membro específico, esse membro pode aprovar ou recusar (explicando o motivo)
    • Ao limpar a equipe, o líder remove os recursos compartilhados; se ainda houver membros ativos, a limpeza falha, então é preciso encerrá-los primeiro

Como a equipe de agentes funciona internamente

  • Caminhos para iniciar a equipe

    • Solicitação do usuário: descreve uma tarefa adequada para trabalho paralelo e pede explicitamente a criação de uma equipe de agentes
    • Sugestão do Claude: se o Claude julgar que o trabalho se beneficia de paralelismo, ele propõe criar a equipe; o processo só continua após confirmação do usuário
    • Em ambos os casos, a equipe nunca é criada sem aprovação do usuário

  • Componentes da arquitetura

    • Team lead: a sessão principal do Claude Code, responsável por criar a equipe, gerar membros e coordenar o trabalho
    • Teammates: instâncias separadas do Claude Code, cada uma executando a tarefa que lhe foi atribuída
    • Task list: lista compartilhada de itens de trabalho que os membros assumem e concluem
    • Mailbox: sistema de mensagens para comunicação entre agentes
    • As dependências entre tarefas são gerenciadas automaticamente; quando um membro conclui uma tarefa, tarefas bloqueadas são desbloqueadas sem intervenção manual
    • A configuração da equipe é salva localmente em ~/.claude/teams/{team-name}/config.json, e a lista de tarefas em ~/.claude/tasks/{team-name}/
    • O config inclui um array members com o nome, o ID do agente e o tipo de agente de cada membro

  • Permissões

    • Os membros são iniciados herdando as configurações de permissão do líder; se o líder rodar com --dangerously-skip-permissions, isso também se aplica a todos os membros
    • Depois de gerados, é possível alterar o modo de cada membro individualmente, mas não definir permissões específicas por membro no momento da criação

  • Contexto e comunicação

    • Cada membro tem sua própria janela de contexto e, ao ser gerado, carrega o mesmo contexto do projeto de uma sessão normal, incluindo CLAUDE.md, servidores MCP e skills
    • O histórico de conversa do líder não é repassado aos membros; apenas o prompt de criação é enviado
    • Entrega automática de mensagens: mensagens enviadas por um membro são entregues automaticamente ao destinatário, sem necessidade de polling pelo líder
    • Notificações de ociosidade: quando um membro termina o trabalho e para, o líder é avisado automaticamente
    • Lista de tarefas compartilhada: todos os agentes podem verificar o estado das tarefas e assumir trabalho disponível
    • Há dois tipos de mensagem: message (para um membro específico) e broadcast (para toda a equipe; como o custo cresce com o tamanho da equipe, deve ser usado com moderação)

  • Uso de tokens

    • Agent Teams aumenta consideravelmente o uso de tokens em comparação com uma sessão única, e esse consumo cresce com o número de membros ativos
    • Em pesquisa, revisão e desenvolvimento de novas funcionalidades, esse custo adicional costuma valer a pena; para trabalho rotineiro, uma única sessão tende a ser mais econômica

Casos de uso

  • Revisão de código em paralelo

    • Um único revisor tende a focar em um tipo de problema por vez, então os critérios de revisão podem ser divididos em domínios independentes como segurança, desempenho e cobertura de testes
    • Cada revisor aplica um filtro diferente ao mesmo PR, e o líder consolida os resultados ao final

  • Investigação com hipóteses concorrentes

    • Um único agente tende a parar a exploração ao encontrar uma explicação plausível, por isso os membros podem ser organizados explicitamente em uma estrutura adversarial
    • Cada membro investiga sua própria hipótese enquanto tenta refutar a teoria dos outros, em um formato de debate científico
    • Isso evita o viés de ancoragem típico de investigações sequenciais e aumenta a chance de a teoria sobrevivente ser a causa raiz real

Boas práticas

  • Forneça contexto suficiente aos membros: o contexto do projeto é carregado automaticamente, mas o histórico de conversa do líder não é compartilhado, então o prompt de criação deve incluir os detalhes relevantes da tarefa
  • Ajuste bem o tamanho das tarefas: se forem pequenas demais, o overhead de coordenação supera o ganho; se forem grandes demais, há risco de trabalho desperdiçado por longos períodos sem check-in; o ideal são unidades autocontidas com entregáveis claros, como funções, arquivos de teste ou revisões
  • Se o líder começar a implementar diretamente no lugar dos membros, instrua com "Wait for your teammates to complete their tasks before proceeding"
  • No primeiro uso, comece com tarefas de pesquisa e revisão com fronteiras claras e sem escrita de código (como revisão de PR, análise de bibliotecas ou investigação de bugs)
  • Evite conflitos de arquivo: se dois membros editarem o mesmo arquivo, um pode sobrescrever o outro; divida o trabalho para que cada membro cuide de conjuntos de arquivos diferentes
  • Acompanhe periodicamente o progresso dos membros, redirecione abordagens ineficazes e consolide os resultados assim que forem surgindo

Solução de problemas

  • Se os membros não aparecerem: no modo in-process, use Shift+Down para alternar entre os membros ativos; verifique se a tarefa é complexa o suficiente para justificar uma equipe; ao pedir split pane, confirme se o tmux está instalado no PATH; no iTerm2, confira se o CLI it2 está instalado e se a Python API está ativada
  • Prompts de permissão em excesso: como os pedidos de permissão dos membros sobem para o líder, pré-aprove tarefas comuns nas configurações de permissão antes de gerar os membros
  • Membro interrompido após erro: verifique a saída desse membro e envie instruções adicionais diretamente, ou gere um membro substituto para continuar o trabalho
  • Líder encerrado antes do fim do trabalho: instrua o líder a continuar ou configure para esperar a conclusão dos membros antes de delegar
  • Sessões tmux órfãs: se restarem sessões tmux após o encerramento da equipe, verifique com tmux ls e remova com tmux kill-session -t <session-name>

Limitações

  • Não é possível restaurar sessões de membros in-process: /resume e /rewind não restauram membros in-process, e após a restauração o líder pode tentar mandar mensagens para membros inexistentes, exigindo a criação de novos membros
  • Atraso no estado das tarefas: se um membro não marcar uma tarefa como concluída, tarefas dependentes podem continuar bloqueadas; atualize o estado manualmente ou peça ao líder para cobrar o membro
  • Atraso no encerramento: um membro só é encerrado depois de terminar a solicitação atual ou a chamada de ferramenta em andamento
  • Apenas uma equipe por sessão: para iniciar uma nova equipe, é preciso limpar a equipe atual primeiro
  • Sem equipes aninhadas: membros não podem criar sua própria equipe nem gerar outros membros; apenas o líder pode gerenciar a equipe
  • Líder fixo: a sessão que criou a equipe é o líder permanente; não é possível promover um membro a líder nem transferir a liderança
  • Permissões em lote na criação: todos os membros começam com o modo de permissão do líder, e não é possível definir permissões por membro no momento da criação
  • Split pane requer tmux ou iTerm2: o modo split-pane não é suportado no terminal integrado do VS Code, Windows Terminal nem Ghostty

Leituras relacionadas

2 comentários

 
kuthia 2026-02-06

Para a orquestração multiagente, parece que vai se tornar importante como preservar resultados semânticos no processo de compressão de contexto. Parece ciência cognitiva.
 
GN⁺ 2026-02-06
Comentários no Hacker News

  • É interessante como a inovação do último ano foi, em grande parte, centrada em engenharia
    Surgiram vários conceitos novos, como MCP, agent e skill, mas problemas fundamentais como alucinação, imprecisão e colapso de contexto ainda não foram resolvidos
    Parece que isso só vai ser resolvido não com engenharia simples, mas com pesquisa fundamental
    As melhorias e anúncios atuais parecem parte de um ciclo de hype para manter as expectativas dos investidores
    Sinceramente, já estou cansado da narrativa em torno de IA e queria passar logo para a fase em que fique claro onde essa tecnologia realmente é útil

  • Esse tipo de recurso é legal, mas fico na dúvida de quantas pessoas realmente conseguem rodar agents o dia inteiro
    Usando Cursor, o consumo de tokens era tão alto que fiz upgrade para o Ultra, mas não parece que o uso acompanha isso proporcionalmente
    Ainda bem que o ecossistema de LLMs open source está avançando rápido, então dá para ter esperança

    • Eu nem consigo usar todo o limite de 200 vezes por mês do Claude Max. Programo todo dia e faço tarefas bem pesadas, e mesmo assim não chego nisso
    • Isso ainda está, na prática, em fase experimental, então pode fracassar como Gas Town
    • Muitas empresas conseguem contratar um engenheiro júnior de US$ 150 mil por ano. Se a assinatura de IA custa mais do que isso, é um problema
      Além disso, aqui não estamos falando de Cursor, e sim de Claude Code. Eu recomendaria usar Claude Max em vez disso
    • Parece que só uma startup de duas pessoas bancadas por VC conseguiria rodar isso o dia inteiro
    • Claude Code Max entrega 30 vezes mais valor por custo de token, então se você não consegue usar tudo, a culpa é sua. Talvez saia até mais barato que a conta de luz

  • Steve Yegge já tinha sugerido no passado a empresas como a Anthropic a ideia de um agent orchestrator
    (Welcome to Gas Town)
    Ver a Anthropic lançar agora o Agent Teams sugere que eles já vinham se preparando desde então, ou chegaram à mesma conclusão
    De qualquer forma, é interessante ver a visão do Steve sendo validada. Talvez a temporada de “domar polecats” esteja chegando

    • Eu também não conhecia GasTown nem Beeds, mas acabei construindo algo parecido. Era um próximo passo tão natural
      claude-code-orchestrator
    • Antes mesmo da febre do GasTown, eu já tinha montado uma estrutura simples de time de agents. Rodava várias instâncias do Claude em sessões tmux e sincronizava com .claude.lock
      Funcionava muito bem, mas ainda não é eficiente. A velocidade de escrita de especificações e a qualidade do QA são os gargalos
    • Na verdade, essa estrutura já existia como conceito em frameworks de actors. Comparando com sistemas como Akka, não há nada realmente novo
      Ver os provedores de LLM aprendendo isso só agora passa a impressão de que eles estão amadurecendo em tempo real
      Chamar isso de Kubernetes para agents nem é exagero. Eu também conecto assim localmente
    • Acho impossível que os engenheiros da Anthropic não conhecessem esse tipo de ideia. Já se falava muito disso desde os primórdios do ChatGPT
    • Na verdade, esses sistemas multi-agent já apareciam bastante no arXiv e no GitHub desde 2023
      Na época, os modelos eram menos inteligentes e a janela de contexto era menor; agora isso só se tornou viável de fato

  • Eu já vinha usando um fluxo de trabalho em que várias instâncias do Claude Code colaboram como CLI agents baseados em tmux
    Esse novo recurso de orquestração é bem mais útil porque compartilha uma lista comum de tarefas e deixa o agent principal coordenar tudo
    Dá para automatizar a colaboração entre agents com a ferramenta tmux-cli

  • Eu não tinha aprendido isso até agora porque parecia óbvio que esse tipo de recurso acabaria sendo embutido por padrão algum dia; agora parece ser a hora de testar

  • Tenho receio de que minha assinatura de US$ 20/mês não aguente nem 10 minutos

    • Se for para pagar do próprio bolso, faz mais sentido usar Kimi ou GLM
    • Também penso assim. Tenho dúvidas se essa estrutura realmente consegue gerar valor
    • Em algumas tarefas específicas, o Haiku deu resultados muito bons

  • Isso parece Gas Town

    • Quando um projeto vai longe demais no bizarro ou brincalhão, as chances são grandes de surgir um clone menos infantil e acabar vencendo
    • Mas aí fica a pergunta: onde foi parar o polecat? Fico curioso com o senso de humor do mercado
    • Não sei exatamente o que é Gas Town, mas eu já vinha usando uma estrutura parecida com Claude Code Agent Teams
      Se você cria sub-agents a partir da conversa principal e divide as tarefas, dá para trabalhar por muito tempo sem perder contexto
    • O design parece mais simples. Um agent líder e vários workers, algo mais limpo do que o sistema complexo de papéis do Gas Town
    • Mas a falta do polecat é uma pena

  • Eu não consigo deixar o Claude Code tocar tarefas grandes de forma independente
    Para manter a qualidade do código, preciso intervir diretamente no processo de design
    Acho que times de agents só aumentariam a carga de revisão e refatoração

    • Se você codificar como skill a estrutura do codebase e as regras de uso de padrões, pode fazer os sub-agents fiscalizarem isso
      Essa ideia de dividir agents de planejamento, design, QA e revisão para colaborarem é justamente a essência desse recurso
    • Também dá para criar um modelo adversarial dentro do Claude para melhorar a qualidade. Um agent faz a modificação e outro valida
    • Assim como humanos dividem tarefas grandes em partes, também é eficiente fazer o Claude definir critérios de planejamento e teste
    • Na prática, em uma de cada 3 ou 4 vezes é preciso ajustar ou interromper. Só gente experiente percebe isso
    • Também há pesquisa em andamento sobre como LLMs dividem trabalho e combinam resultados
      artigo relacionado

  • Estou procurando uma orquestração multi-LLM em que o Opus fique como principal e os sub-agents rodem em Gemini ou Codex

    • Ferramentas que suportam esse tipo de estrutura incluem Coder-Codex-Gemini, ccg-workflow e claude_code_bridge
      Todos são projetos feitos por desenvolvedores chineses, mas, pelo que usei, são excelentes
    • Com AgentWorkforce/relay, dá para definir qualquer LLM que você quiser como líder/orquestrador
      Resumi minha experiência neste post no Twitter
    • Eu programo com Opus e faço revisão com Codex. Em cada tarefa, chamo uma review skill para executar o Codex
      código da review skill, junto com o analisador de PR da Greptile
    • Se o Cursor passar a suportar esse tipo de colaboração entre múltiplos modelos, isso será realmente útil
    • Como no exemplo do Pied-Piper,
      também seria possível montar uma estrutura em que o GPT-5.2 Codex Max faz o planejamento, o Opus 4.5 faz a implementação e o Gemini faz a revisão

  • Ao criar minha própria alternativa ao Beads, acabei concluindo um sistema de agents sincronizado com projetos do GitHub com estrutura parecida
    Pretendo abrir o código em breve, e acho que integrar isso a um sistema de tickets será mais útil no longo prazo
    É desejável que surjam mais alternativas agnósticas que não fiquem presas a um agent específico