Nota do autor: Um guia passo a passo para ativar e usar a funcionalidade de colaboração multi-agente Claude 4.6 Agent Teams, dominando a arquitetura Lead + Teammate, atribuição de tarefas, comunicação por mensagens e técnicas práticas.
Com o lançamento do Claude Opus 4.6, foi introduzido simultaneamente o recurso Agent Teams (Equipes de Agentes), permitindo que múltiplas instâncias do Claude colaborem em paralelo como uma verdadeira equipe de desenvolvimento. Muitos desenvolvedores estão curiosos: como ativar o Agent Teams? Como acioná-lo? Qual a diferença para um Subagent? Para quais cenários ele é indicado?
Valor central: Ao terminar de ler este artigo, você dominará o fluxo completo de uso do Agent Teams — desde a configuração inicial até os comandos de ativação, da distribuição de tarefas à colaboração em equipe, permitindo que você comece a programar com multi-agentes imediatamente.
O que é o Claude Agent Teams
O Agent Teams é uma funcionalidade experimental do Claude Code (em fase de prévia de pesquisa) que permite executar múltiplas instâncias independentes do Claude Code simultaneamente em um projeto, colaborando por meio de uma lista de tarefas compartilhada e um sistema de mensagens.
Entenda em uma frase: Agent Teams = um Lead (líder da equipe) + múltiplos Teammates (colegas de equipe), cada um trabalhando de forma independente, comunicando-se entre si e completando tarefas complexas juntos.
| Dimensão de Comparação | Subagent (Subagente) | Agent Teams (Equipe) |
|---|---|---|
| Forma de comunicação | Reporta apenas resultados ao agente principal | Colegas podem se comunicar diretamente |
| Forma de coordenação | Agente principal gerencia tudo | Lista de tarefas compartilhada + autoatribuição |
| Contexto | Contexto independente, resultado retorna ao chamador | Contexto independente, autonomia total |
| Melhor cenário | Tarefas focadas que precisam apenas de um resultado | Tarefas complexas que exigem discussão e colaboração |
| Consumo de Tokens | Menor (resultados consolidados no contexto principal) | Maior (cada colega é uma instância independente do Claude) |
Arquitetura central do Claude Agent Teams
O Agent Teams é composto por 4 componentes principais:
| Componente | Responsabilidade | Descrição |
|---|---|---|
| Lead Agent | Líder da Equipe | Sua sessão principal do Claude Code, responsável por criar a equipe, atribuir tarefas e consolidar resultados |
| Teammate | Colega de Equipe | Instâncias independentes do Claude Code, cada uma executando as tarefas atribuídas |
| Task List | Lista de Tarefas Compartilhada | Um quadro de tarefas visível para todos, suportando reivindicação, dependências e rastreamento de status |
| Mailbox | Sistema de Mensagens | Canal de comunicação entre colegas, suportando mensagens privadas e transmissões (broadcast) |
💡 Diferença crucial: O Subagent segue o modelo de "subordinação e reporte", enquanto o Agent Teams segue o modelo de "colaboração em equipe". Se sua tarefa exige que várias pessoas discutam, desafiem pontos de vista ou processem diferentes módulos em paralelo, o Agent Teams é a melhor escolha.
Como ativar o Claude Agent Teams
O Agent Teams vem desativado por padrão e precisa ser habilitado manualmente. Aqui estão as 3 formas de fazer isso:
Passo 1: Ativar a funcionalidade experimental
Forma A — Arquivo de configuração (Recomendado)
No arquivo settings.json do Claude Code, adicione:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
Forma B — Variável de ambiente
# Adicione ao seu .bashrc ou .zshrc
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
Forma C — Sessão única
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude
Passo 2: Acionar o Agent Teams com linguagem natural
Não existe um comando de barra como /agent-teams. Após ativar a função, você só precisa descrever a equipe que deseja usando linguagem natural:
Crie um agent team para revisar o PR #142. Gere três revisores:
- Um focado em riscos de segurança
- Um para verificar o impacto na performance
- Um para validar a cobertura de testes
Peça que cada um reporte suas descobertas após a revisão.
Ou de forma mais simples:
Create a team with 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.
O Claude criará a equipe automaticamente, gerará os colegas e atribuirá as tarefas. O Claude também pode sugerir proativamente a criação de uma equipe — se ele julgar que sua tarefa é adequada para processamento paralelo, mas ele pedirá sua confirmação primeiro.
Passo 3: Escolher o modo de exibição
| Modo de exibição | Descrição | Ambiente aplicável |
|---|---|---|
| in-process (padrão) | Todos os colegas rodam no terminal principal | Qualquer terminal, incluindo VS Code |
| tmux | Cada colega em um painel independente | Requer tmux ou iTerm2 |
| auto | Decisão automática | Divide a tela se já estiver no tmux, caso contrário, in-process |
# Especificar via linha de comando
claude --teammate-mode tmux
# Ou configurar no settings.json
{
"teammateMode": "tmux"
}
Dica: Para o primeiro uso, sugerimos o modo
in-process. Depois de se familiarizar, tente o modo de divisão de tela comtmux. Ao obter créditos da API do Claude via APIYI (apiyi.com), você pode testar diversas configurações do Agent Teams localmente com total flexibilidade.
Guia de Operação do Claude Agent Teams
Atalhos de Teclado Rápidos
Enquanto o Agent Teams estiver em execução, você pode usar os seguintes atalhos:
| Atalho | Função |
|---|---|
| Shift+Up/Down | Alternar/selecionar diferentes colegas de equipe |
| Enter | Ver detalhes da conversa do colega selecionado |
| Escape | Interromper a operação atual do colega |
| Ctrl+T | Alternar visualização da lista de tarefas |
| Shift+Tab | Alternar modo de delegação (O Lead apenas coordena, não coda) |
Mecanismo de Atribuição e Resgate de Tarefas
O sistema de tarefas do Agent Teams suporta 3 estados e relações de dependência:
Estados da Tarefa: pending (aguardando) → in_progress (em andamento) → completed (concluída)
Mecanismo de Dependência: As tarefas podem configurar a dependência blockedBy. Assim que a tarefa da qual ela depende é concluída, a tarefa seguinte é desbloqueada automaticamente, sem necessidade de intervenção manual.
Formas de Atribuição:
- Atribuição Direta pelo Lead: Diga explicitamente ao Lead para atribuir uma tarefa específica a um colega determinado.
- Autoatribuição: Após concluir a tarefa atual, o colega assume automaticamente a próxima tarefa disponível e não atribuída.
- Bloqueio de Arquivo (File Lock): Se vários colegas tentarem pegar a mesma tarefa ao mesmo tempo, o sistema usa um bloqueio de arquivo para evitar conflitos.
Sugestão de Tamanho de Tarefa: A melhor prática é atribuir de 5 a 6 tarefas para cada colega. Tarefas muito pequenas geram um custo de coordenação maior que o benefício, enquanto tarefas muito grandes fazem com que o colega demore demais para reportar o progresso.
Formas de Comunicação entre Colegas
| Tipo de Comunicação | Descrição | Cenário de Uso |
|---|---|---|
| write (mensagem privada) | Envia uma mensagem para um colega específico | Coordenar questões pontuais |
| broadcast (transmissão) | Envia uma mensagem para todos os colegas | Avisos importantes (use com moderação, o custo cresce com o tamanho da equipe) |
A comunicação é ponto a ponto, não precisando passar pela intermediação do Lead. Qualquer colega pode enviar mensagens diretamente para outros.
Colaboração via Git e Como Evitar Conflitos de Arquivos
A regra mais importante no Agent Teams: dois colegas editando o mesmo arquivo causarão sobreposição (overwrite).
Estratégia recomendada de divisão de arquivos:
# Exemplo de desenvolvimento de funcionalidade Full-stack
Colega Backend → Responsável por src/api/ e src/migrations/
Colega Frontend → Responsável por src/components/
Colega Testes → Responsável por tests/
⚠️ Importante: Os colegas do Agent Teams compartilham o mesmo diretório de trabalho e não utilizam git worktree automaticamente. Garantir que cada colega seja responsável por um conjunto diferente de arquivos é a chave para evitar conflitos.
5 Cenários Reais do Claude Agent Teams
Cenário 1: Revisão de Código Multi-ângulo
Crie um agent team para revisar este PR:
- Revisor de Segurança: verifique injeção, XSS, permissões e outros problemas de segurança.
- Revisor de Performance: analise consultas N+1, vazamentos de memória e estratégias de cache.
- Revisor de Testes: valide a cobertura de testes e casos de borda.
Peça que cada um reporte suas descobertas após a revisão.
Por que é ideal para o Agent Teams: As três dimensões de revisão são completamente independentes, não geram conflitos de arquivos e podem ser executadas em paralelo.
Cenário 2: Desenvolvimento Paralelo de Novos Módulos
Crie uma equipe para construir o sistema de notificações do usuário:
- Colega 1: Construa a API backend (src/api/notifications/)
- Colega 2: Construa os componentes frontend (src/components/notifications/)
- Colega 3: Escreva os testes de integração (tests/notifications/)
Por que é ideal: Cada colega é responsável por um diretório diferente, garantindo isolamento natural. Basta mesclar (merge) ao finalizar.
Cenário 3: Debugging de Hipóteses Concorrentes
Existe um bug intermitente. Crie uma equipe para debugá-lo usando diferentes hipóteses:
- Colega A: investigue se é uma condição de corrida (race condition).
- Colega B: investigue se é um vazamento de memória (memory leak).
- Colega C: investigue se é um timeout de uma API de terceiros.
Cada um deve validar sua hipótese de forma independente e reportar.
Por que é ideal: Debugging adversarial, onde múltiplas pistas são investigadas em paralelo. Quem encontrar a causa raiz primeiro, vence.
Cenário 4: Coordenação de Mudanças Cross-layer
Quando uma alteração abrange frontend, backend e banco de dados, o Agent Teams permite que especialistas de cada camada cuidem de suas partes, coordenando as definições de interface através do sistema de mensagens.
Cenário 5: Pesquisa Exploratória
Estou projetando uma ferramenta de CLI para rastrear comentários TODO no código.
Crie uma equipe para explorar de diferentes ângulos:
- Um colega responsável pelo design da experiência do usuário (UX).
- Um colega responsável pela arquitetura técnica.
- Um colega no papel de "advogado do diabo" (questionador).
Por que é ideal: Colisão de múltiplas perspectivas, onde um desafia as hipóteses e conclusões do outro.
Guia de Seleção: Claude Agent Teams vs. Subagent
| Dimensão de Avaliação | Escolher Subagent | Escolher Agent Teams |
|---|---|---|
| Os colegas precisam se comunicar? | ❌ Não | ✅ Sim |
| A tarefa pode ser paralelizada? | Parcialmente | ✅ Altamente paralelizável |
| Envolve edição de múltiplos arquivos? | ✅ Seguro para o mesmo arquivo | ⚠️ Exige divisão para evitar conflitos |
| Complexidade da tarefa? | Foco em um único objetivo | Múltiplas perspectivas e módulos |
| Orçamento de Tokens? | 💰 Mais econômico | 💸 Consumo aprox. 3-7 vezes maior |
| Precisa de discussão/questionamento? | ❌ | ✅ |
Referência de custo: Um time de 3 agentes rodando por 30 minutos consome cerca de 3 a 4 vezes mais tokens que uma sessão individual. No modo Plan, o consumo chega a cerca de 7 vezes. Recomendo gerenciar seu orçamento de tokens de forma flexível através do APIYI (apiyi.com).
Dicas Avançadas para Claude Agent Teams
Dica 1: Modelos híbridos para reduzir custos
Crie um time onde o Lead use Opus e os 4 colegas usem Sonnet.
O Lead fica responsável pelas decisões estratégicas usando o Opus 4.6 para garantir a qualidade, enquanto os colegas executam tarefas específicas com o Sonnet para controlar os custos.
Dica 2: Fluxo de aprovação de Plan (Plano)
Gere um colega arquiteto para refatorar o módulo de autenticação.
Exija que ele envie a proposta para aprovação antes de fazer qualquer alteração.
O colega entrará primeiro em um modo Plan de apenas leitura. Após concluir a proposta, ele enviará uma solicitação de aprovação ao Lead. O colega só começará a implementação após a autorização do Lead.
Dica 3: Modo de delegação para evitar que o Lead "ponha a mão na massa"
Pressione Shift+Tab para ativar o modo de delegação. Assim, o Lead focará apenas em coordenar e distribuir as tarefas, sem escrever o código sozinho. Isso evita que o Lead acabe "roubando o trabalho" dos outros.
Dica 4: Quality Gate Hooks (Ganchos de Controle de Qualidade)
Utilize o mecanismo de Hooks para controlar a qualidade automaticamente:
TeammateIdle: Ativado quando um colega está prestes a ficar ocioso; o código de saída 2 pode enviar um feedback para que o colega continue trabalhando.TaskCompleted: Ativado quando uma tarefa é marcada como concluída; o código de saída 2 pode impedir a finalização e exigir correções.
Considerações sobre o Claude Agent Teams
Limitações Conhecidas
- Sem suporte para retomada de sessão: Os comandos
/resumee/rewindnão restauram colegas de equipe (teammates) que já foram encerrados. - Uma equipe por sessão: O Lead só consegue gerenciar uma única equipe por vez.
- Sem suporte para equipes aninhadas: Os teammates não podem criar suas próprias subequipes.
- Herança de permissões: Os teammates herdam o modo de permissão do Lead, mas isso pode ser ajustado individualmente após a criação.
- Limitações do modo de tela dividida: A divisão de tela via tmux não é compatível com o terminal integrado do VS Code, Windows Terminal ou Ghostty.
- Falha de teammates: Se um teammate travar, isso ativará um timeout de "heartbeat" de 5 minutos; suas tarefas poderão então ser assumidas por outros colegas.
Melhores Práticas
- Tamanho da equipe: Recomendamos entre 2 e 5 teammates. Geralmente, uma equipe de 3 pessoas funciona melhor do que uma de 6.
- A divisão de tarefas é mais importante que o número de pessoas: Uma equipe de 3 pessoas com tarefas bem divididas é muito mais eficiente que uma de 6 com divisões mal planejadas.
- Tarefas intensivas em leitura (como revisão de código e pesquisa) são o "ponto ideal" (sweet spot) do Agent Teams.
- Edição simultânea intensiva em escrita ainda é um desafio e exige uma divisão de arquivos muito rigorosa para evitar conflitos.
Perguntas Frequentes
Q1: Qual assinatura é necessária para usar o Agent Teams?
O Agent Teams é um recurso experimental do Claude Code e exige uma assinatura Claude Max (entre US$ 100 e US$ 200/mês) para garantir cotas suficientes do Opus 4.6. Para usuários de API, a cobrança segue as taxas padrão do Opus 4.6 (US$ 5 para entrada e US$ 25 para saída por milhão de tokens). Você também pode encontrar planos de faturamento mais flexíveis através da plataforma APIYI (apiyi.com).
Q2: O Agent Teams só funciona com o Opus 4.6?
Não. Embora o Agent Teams tenha sido lançado junto com o Opus 4.6, você pode misturar diferentes modelos. O padrão recomendado é usar o Opus 4.6 como Lead para tomar decisões estratégicas e o Sonnet para os teammates executarem as tarefas práticas. Isso ajuda a manter a qualidade da coordenação enquanto controla os custos.
Q3: O Agent Teams funciona no VS Code?
Sim, mas com algumas restrições. O terminal integrado do VS Code suporta o modo "in-process" (onde todos os teammates rodam dentro do mesmo terminal). No entanto, o modo de tela dividida via tmux não funciona no VS Code, sendo necessário utilizar um terminal externo para essa funcionalidade.
Resumo
Pontos principais do Claude 4.6 Agent Teams:
- Como ativar: Defina a variável de ambiente
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1e, em seguida, descreva a equipe usando linguagem natural. - Padrão de arquitetura: Lead Agent (Agente Líder) coordena + Teammate Agents (Agentes de Equipe) trabalham em paralelo, colaborando por meio de uma lista de tarefas compartilhada e um sistema de mensagens.
- Melhores cenários: Revisão de código, desenvolvimento paralelo de novos módulos, depuração de hipóteses concorrentes, coordenação entre camadas e pesquisa exploratória.
- Princípio fundamental: A divisão de tarefas é mais importante do que o número de pessoas; 3 colegas de equipe costumam funcionar melhor do que 6.
- Controle de custos: O modelo híbrido (Lead com Opus + colegas com Sonnet) é a melhor opção em termos de custo-benefício.
O Agent Teams leva a programação com IA da era do "trabalho solo" para a era da "colaboração em equipe". Embora ainda esteja em fase de visualização de pesquisa (research preview), ele já demonstra uma poderosa capacidade de desenvolvimento paralelo.
Recomendamos obter créditos da API do Claude através do APIYI (apiyi.com). A plataforma oferece faturamento flexível e suporte a múltiplos modelos, facilitando o teste de várias configurações do Agent Teams.
📚 Referências
⚠️ Observação sobre o formato dos links: Todos os links externos usam o formato
Nome da fonte: domain.com, facilitando a cópia, mas sem links clicáveis para evitar a perda de autoridade de SEO.
-
Documentação oficial do Claude Code Agent Teams: Guia completo de uso do Agent Teams
- Link:
code.claude.com/docs/en/agent-teams - Descrição: Documentação oficial contendo métodos de ativação, explicações de arquitetura e melhores práticas.
- Link:
-
Blog de Engenharia da Anthropic — Caso do Compilador C: 16 Claudes construindo um compilador C em paralelo
- Link:
anthropic.com/engineering/building-c-compiler - Descrição: Caso real de uso do Agent Teams em larga escala, com mais de 2000 sessões gerando 100 mil linhas de código.
- Link:
-
Addy Osmani — Claude Code Swarms: Análise profunda do Agent Teams pelo líder de engenharia do Google
- Link:
addyosmani.com/blog/claude-code-agent-teams - Descrição: Análise de arquitetura e sugestões de melhores práticas.
- Link:
-
Anúncio de lançamento do Claude Opus 4.6: Notas oficiais de lançamento
- Link:
anthropic.com/news/claude-opus-4-6 - Descrição: Apresentação oficial da funcionalidade Agent Teams.
- Link:
Autor: Equipe APIYI
Troca de conhecimentos: Sinta-se à vontade para discutir sua experiência com o Claude Agent Teams na seção de comentários. Para mais materiais, visite a comunidade técnica do APIYI (apiyi.com).
