Equipes de agentes requerem Claude Code v2.1.32 ou posterior. Verifique sua versão com
claude --version.- Quando usar equipes de agentes, incluindo os melhores casos de uso e como elas se comparam com subagents
- Iniciando uma equipe
- Controlando companheiros de equipe, incluindo modos de exibição, atribuição de tarefas e delegação
- Melhores práticas para trabalho paralelo
Quando usar equipes de agentes
Equipes de agentes são mais eficazes para tarefas onde a exploração paralela adiciona valor real. Veja exemplos de casos de uso para cenários completos. Os casos de uso mais fortes são:- Pesquisa e revisão: múltiplos companheiros de equipe podem investigar diferentes aspectos de um problema simultaneamente, depois compartilhar e desafiar as descobertas uns dos outros
- Novos módulos ou recursos: companheiros de equipe podem possuir cada uma uma peça separada sem se atrapalharem
- Depuração com hipóteses concorrentes: companheiros de equipe testam diferentes teorias em paralelo e convergem para a resposta mais rapidamente
- Coordenação entre camadas: mudanças que abrangem frontend, backend e testes, cada uma de propriedade de um companheiro de equipe diferente
Comparar com subagents
Tanto equipes de agentes quanto subagents permitem que você paralelizar o trabalho, mas operam de forma diferente. Escolha com base em se seus trabalhadores precisam se comunicar uns com os outros:
| Subagents | Agent teams | |
|---|---|---|
| Context | Context window própria; resultados retornam ao chamador | Context window própria; totalmente independente |
| Communication | Relatam resultados de volta apenas ao agente principal | Companheiros de equipe se mensageiam diretamente |
| Coordination | Agente principal gerencia todo o trabalho | Lista de tarefas compartilhada com auto-coordenação |
| Best for | Tarefas focadas onde apenas o resultado importa | Trabalho complexo que requer discussão e colaboração |
| Token cost | Menor: resultados resumidos de volta ao contexto principal | Maior: cada companheiro de equipe é uma instância Claude separada |
Ativar equipes de agentes
Equipes de agentes são desabilitadas por padrão. Ative-as definindo a variável de ambienteCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS como 1, seja no seu ambiente de shell ou através de settings.json:
settings.json
Inicie sua primeira equipe de agentes
Após ativar equipes de agentes, diga ao Claude para criar uma equipe de agentes e descreva a tarefa e a estrutura da equipe que você deseja em linguagem natural. Claude cria a equipe, gera companheiros de equipe e coordena o trabalho com base no seu prompt. Este exemplo funciona bem porque os três papéis são independentes e podem explorar o problema sem esperar um pelo outro:Controle sua equipe de agentes
Diga ao líder o que você quer em linguagem natural. Ele lida com coordenação de equipe, atribuição de tarefas e delegação com base em suas instruções.Escolha um modo de exibição
Equipes de agentes suportam dois modos de exibição:- In-process: todos os companheiros de equipe são executados dentro do seu terminal principal. Use Shift+Down para percorrer os companheiros de equipe e digite para enviar mensagens para eles diretamente. Funciona em qualquer terminal, nenhuma configuração extra necessária.
- Split panes: cada companheiro de equipe recebe seu próprio painel. Você pode ver a saída de todos de uma vez e clicar em um painel para interagir diretamente. Requer tmux ou iTerm2.
tmux tem limitações conhecidas em certos sistemas operacionais e tradicionalmente funciona melhor no macOS. Usar tmux -CC no iTerm2 é o ponto de entrada sugerido para tmux."auto", que usa split panes se você já estiver executando dentro de uma sessão tmux, e in-process caso contrário. A configuração "tmux" ativa o modo split-pane e detecta automaticamente se deve usar tmux ou iTerm2 com base no seu terminal. Para substituir, defina teammateMode no seu settings.json:
it2. Para instalar manualmente:
- tmux: instale através do gerenciador de pacotes do seu sistema. Veja o wiki tmux para instruções específicas da plataforma.
- iTerm2: instale o CLI
it2, depois ative a API Python em iTerm2 → Settings → General → Magic → Enable Python API.
Especifique companheiros de equipe e modelos
Claude decide o número de companheiros de equipe a gerar com base em sua tarefa, ou você pode especificar exatamente o que deseja:Exigir aprovação de plano para companheiros de equipe
Para tarefas complexas ou arriscadas, você pode exigir que os companheiros de equipe planejem antes de implementar. O companheiro de equipe trabalha em modo de plano somente leitura até que o líder aprove sua abordagem:Fale com companheiros de equipe diretamente
Cada companheiro de equipe é uma sessão Claude Code completa e independente. Você pode enviar mensagens para qualquer companheiro de equipe diretamente para dar instruções adicionais, fazer perguntas de acompanhamento ou redirecionar sua abordagem.- Modo in-process: use Shift+Down para percorrer os companheiros de equipe, depois digite para enviar uma mensagem. Pressione Enter para visualizar a sessão de um companheiro de equipe, depois Escape para interromper seu turno atual. Pressione Ctrl+T para alternar a lista de tarefas.
- Modo split-pane: clique em um painel de companheiro de equipe para interagir com sua sessão diretamente. Cada companheiro de equipe tem uma visualização completa de seu próprio terminal.
Atribuir e reivindicar tarefas
A lista de tarefas compartilhada coordena o trabalho em toda a equipe. O líder cria tarefas e os companheiros de equipe as trabalham. As tarefas têm três estados: pendente, em progresso e concluída. As tarefas também podem depender de outras tarefas: uma tarefa pendente com dependências não resolvidas não pode ser reivindicada até que essas dependências sejam concluídas. O líder pode atribuir tarefas explicitamente ou os companheiros de equipe podem auto-reivindicar:- Líder atribui: diga ao líder qual tarefa dar a qual companheiro de equipe
- Auto-reivindicar: após terminar uma tarefa, um companheiro de equipe pega a próxima tarefa não atribuída e desbloqueada por conta própria
Encerrar companheiros de equipe
Para encerrar graciosamente a sessão de um companheiro de equipe:Limpar a equipe
Quando você terminar, peça ao líder para limpar:Aplicar gates de qualidade com hooks
Use hooks para aplicar regras quando os companheiros de equipe terminam o trabalho ou as tarefas são concluídas:TeammateIdle: é executado quando um companheiro de equipe está prestes a ficar ocioso. Saia com código 2 para enviar feedback e manter o companheiro de equipe trabalhando.TaskCompleted: é executado quando uma tarefa está sendo marcada como concluída. Saia com código 2 para evitar conclusão e enviar feedback.
Como funcionam as equipes de agentes
Esta seção cobre a arquitetura e a mecânica por trás das equipes de agentes. Se você quiser começar a usá-las, veja Controle sua equipe de agentes acima.Como Claude inicia equipes de agentes
Existem duas maneiras pelas quais as equipes de agentes começam:- Você solicita uma equipe: dê ao Claude uma tarefa que se beneficie do trabalho paralelo e peça explicitamente uma equipe de agentes. Claude cria uma com base em suas instruções.
- Claude propõe uma equipe: se Claude determinar que sua tarefa se beneficiaria do trabalho paralelo, pode sugerir criar uma equipe. Você confirma antes que ele proceda.
Arquitetura
Uma equipe de agentes consiste em:| Componente | Papel |
|---|---|
| Team lead | A sessão Claude Code principal que cria a equipe, gera companheiros de equipe e coordena o trabalho |
| Teammates | Instâncias Claude Code separadas que cada uma trabalha em tarefas atribuídas |
| Task list | Lista compartilhada de itens de trabalho que os companheiros de equipe reivindicam e completam |
| Mailbox | Sistema de mensagens para comunicação entre agentes |
- Team config:
~/.claude/teams/{team-name}/config.json - Task list:
~/.claude/tasks/{team-name}/
members com o nome de cada companheiro de equipe, ID do agente e tipo de agente. Os companheiros de equipe podem ler este arquivo para descobrir outros membros da equipe.
Permissões
Os companheiros de equipe começam com as configurações de permissão do líder. Se o líder for executado com--dangerously-skip-permissions, todos os companheiros de equipe também. Após gerar, você pode alterar modos de companheiros de equipe individuais, mas não pode definir modos por companheiro de equipe no tempo de geração.
Context e comunicação
Cada companheiro de equipe tem sua própria context window. Quando gerado, um companheiro de equipe carrega o mesmo contexto de projeto que uma sessão regular: CLAUDE.md, MCP servers e skills. Ele também recebe o prompt de geração do líder. O histórico de conversa do líder não é transferido. Como os companheiros de equipe compartilham informações:- Entrega automática de mensagens: quando os companheiros de equipe enviam mensagens, elas são entregues automaticamente aos destinatários. O líder não precisa fazer polling para atualizações.
- Notificações de ociosidade: quando um companheiro de equipe termina e para, ele notifica automaticamente o líder.
- Lista de tarefas compartilhada: todos os agentes podem ver o status da tarefa e reivindicar trabalho disponível.
- message: envie uma mensagem para um companheiro de equipe específico
- broadcast: envie para todos os companheiros de equipe simultaneamente. Use com moderação, pois os custos escalam com o tamanho da equipe.
Uso de tokens
Equipes de agentes usam significativamente mais tokens do que uma única sessão. Cada companheiro de equipe tem sua própria context window, e o uso de tokens escala com o número de companheiros de equipe ativos. Para pesquisa, revisão e trabalho de novos recursos, os tokens extras geralmente valem a pena. Para tarefas rotineiras, uma única sessão é mais econômica. Veja custos de token de equipe de agentes para orientação de uso.Exemplos de casos de uso
Estes exemplos mostram como as equipes de agentes lidam com tarefas onde a exploração paralela adiciona valor.Executar uma revisão de código paralela
Um único revisor tende a gravitar em torno de um tipo de problema por vez. Dividir critérios de revisão em domínios independentes significa que segurança, desempenho e cobertura de testes recebem atenção completa simultaneamente. O prompt atribui a cada companheiro de equipe uma lente distinta para que não se sobreponham:Investigar com hipóteses concorrentes
Quando a causa raiz é incerta, um único agente tende a encontrar uma explicação plausível e parar de procurar. O prompt combate isso tornando os companheiros de equipe explicitamente adversários: o trabalho de cada um não é apenas investigar sua própria teoria, mas desafiar as dos outros.Melhores práticas
Dê aos companheiros de equipe contexto suficiente
Os companheiros de equipe carregam contexto de projeto automaticamente, incluindo CLAUDE.md, MCP servers e skills, mas não herdam o histórico de conversa do líder. Veja Context e comunicação para detalhes. Inclua detalhes específicos da tarefa no prompt de geração:Escolha um tamanho de equipe apropriado
Não há limite rígido no número de companheiros de equipe, mas restrições práticas se aplicam:- Custos de token escalam linearmente: cada companheiro de equipe tem sua própria context window e consome tokens independentemente. Veja custos de token de equipe de agentes para detalhes.
- Sobrecarga de coordenação aumenta: mais companheiros de equipe significa mais comunicação, coordenação de tarefas e potencial para conflitos
- Retornos decrescentes: além de um certo ponto, companheiros de equipe adicionais não aceleram o trabalho proporcionalmente
Dimensione tarefas apropriadamente
- Muito pequeno: sobrecarga de coordenação excede o benefício
- Muito grande: companheiros de equipe trabalham muito tempo sem check-ins, aumentando o risco de esforço desperdiçado
- Bem dimensionado: unidades auto-contidas que produzem um entregável claro, como uma função, um arquivo de teste ou uma revisão
Espere os companheiros de equipe terminarem
Às vezes, o líder começa a implementar tarefas em vez de esperar pelos companheiros de equipe. Se você notar isso:Comece com pesquisa e revisão
Se você é novo em equipes de agentes, comece com tarefas que têm limites claros e não requerem escrever código: revisar um PR, pesquisar uma biblioteca ou investigar um bug. Essas tarefas mostram o valor da exploração paralela sem os desafios de coordenação que vêm com a implementação paralela.Evite conflitos de arquivo
Dois companheiros de equipe editando o mesmo arquivo leva a sobrescrita. Divida o trabalho para que cada companheiro de equipe possua um conjunto diferente de arquivos.Monitore e direcione
Verifique o progresso dos companheiros de equipe, redirecione abordagens que não estão funcionando e sintetize descobertas conforme chegam. Deixar uma equipe executar sem supervisão por muito tempo aumenta o risco de esforço desperdiçado.Troubleshooting
Companheiros de equipe não aparecem
Se os companheiros de equipe não aparecerem depois que você pedir ao Claude para criar uma equipe:- No modo in-process, os companheiros de equipe podem já estar em execução, mas não visíveis. Pressione Shift+Down para percorrer os companheiros de equipe ativos.
- Verifique se a tarefa que você deu ao Claude era complexa o suficiente para justificar uma equipe. Claude decide se deve gerar companheiros de equipe com base na tarefa.
- Se você explicitamente solicitou split panes, certifique-se de que tmux está instalado e disponível no seu PATH:
- Para iTerm2, verifique se o CLI
it2está instalado e a API Python está ativada nas preferências do iTerm2.
Muitos prompts de permissão
Solicitações de permissão de companheiros de equipe surgem para o líder, o que pode criar atrito. Pré-aprove operações comuns nas suas configurações de permissão antes de gerar companheiros de equipe para reduzir interrupções.Companheiros de equipe parando em erros
Os companheiros de equipe podem parar após encontrar erros em vez de se recuperar. Verifique sua saída usando Shift+Down no modo in-process ou clicando no painel no modo split, depois:- Dê a eles instruções adicionais diretamente
- Gere um companheiro de equipe de substituição para continuar o trabalho
Líder encerra antes do trabalho estar pronto
O líder pode decidir que a equipe terminou antes de todas as tarefas estarem realmente completas. Se isso acontecer, diga a ele para continuar. Você também pode dizer ao líder para esperar os companheiros de equipe terminarem antes de prosseguir se ele começar a fazer trabalho em vez de delegar.Sessões tmux órfãs
Se uma sessão tmux persistir após a equipe terminar, pode não ter sido totalmente limpa. Liste as sessões e mate a criada pela equipe:Limitações
Equipes de agentes são experimentais. Limitações atuais a serem observadas:- Sem retomada de sessão com companheiros de equipe in-process:
/resumee/rewindnão restauram companheiros de equipe in-process. Após retomar uma sessão, o líder pode tentar enviar mensagens para companheiros de equipe que não existem mais. Se isso acontecer, diga ao líder para gerar novos companheiros de equipe. - Status da tarefa pode ficar atrasado: os companheiros de equipe às vezes falham em marcar tarefas como concluídas, o que bloqueia tarefas dependentes. Se uma tarefa parecer presa, verifique se o trabalho está realmente pronto e atualize o status da tarefa manualmente ou diga ao líder para dar um empurrão ao companheiro de equipe.
- Encerramento pode ser lento: os companheiros de equipe terminam sua solicitação atual ou chamada de ferramenta antes de encerrar, o que pode levar tempo.
- Uma equipe por sessão: um líder pode gerenciar apenas uma equipe por vez. Limpe a equipe atual antes de iniciar uma nova.
- Sem equipes aninhadas: os companheiros de equipe não podem gerar suas próprias equipes ou companheiros de equipe. Apenas o líder pode gerenciar a equipe.
- Líder é fixo: a sessão que cria a equipe é o líder por sua vida útil. Você não pode promover um companheiro de equipe a líder ou transferir liderança.
- Permissões definidas no tempo de geração: todos os companheiros de equipe começam com o modo de permissão do líder. Você pode alterar modos de companheiros de equipe individuais após gerar, mas não pode definir modos por companheiro de equipe no tempo de geração.
- Split panes requerem tmux ou iTerm2: o modo in-process padrão funciona em qualquer terminal. O modo split-pane não é suportado no terminal integrado do VS Code, Windows Terminal ou Ghostty.
Próximos passos
Explore abordagens relacionadas para trabalho paralelo e delegação:- Delegação leve: subagents geram agentes auxiliares para pesquisa ou verificação dentro de sua sessão, melhor para tarefas que não precisam de coordenação entre agentes
- Sessões paralelas manuais: Git worktrees permitem que você execute múltiplas sessões Claude Code você mesmo sem coordenação de equipe automatizada
- Comparar abordagens: veja a comparação subagent vs agent team para um detalhamento lado a lado
