Depender de uma única sessão de AI para fluxos de trabalho complexos e multidomínio é inerentemente lento. Equipes de agents do Claude resolvem isso executando agents especializados em paralelo, entregando resultados mais profundos em velocidades muito maiores. Este guia explica como funcionam as equipes de agents do Claude Code, como configurá-las e as melhores práticas para extrair o máximo valor delas.
O que são equipes de agents do Claude
Equipes de agents do Claude Code são um sistema de coordenação multi-instância em que várias sessões do Claude trabalham em paralelo na mesma base de código. Uma sessão é designada como agent líder, recebe a tarefa geral, a decompõe em subtarefas e sintetiza a entrega final. Os demais sub-agents são colegas; cada um roda em sua própria janela de contexto isolada, assume uma parte discreta do trabalho e se comunica diretamente com outros colegas.
Vantagens das equipes de agents
Equipes de agents diferem dos assistentes de AI típicos, que processam tarefas sequencialmente, uma por vez. Equipes de agents quebram essa limitação: quando o trabalho pode ser genuinamente paralelizado, o tempo de execução cai na mesma medida.
Ao mesmo tempo, equipes de agents são mais do que várias sessões: a camada de coordenação acrescenta três capacidades que o trabalho manual com múltiplas sessões não oferece:
Mensagens ponto a ponto: Colegas podem enviar mensagens diretamente uns aos outros, sem passar por você nem pelo líder. Por exemplo, uma equipe de agents com um revisor de segurança pode sinalizar uma descoberta ao revisor de performance no meio da execução, sem travar toda a equipe.
Bloqueio de arquivos: Quando um colega escreve em um arquivo, ele adquire um bloqueio que impede escritas simultâneas de outros agents. Isso evita a classe de conflitos de merge causada por sobrescritas silenciosas.
Rastreamento de dependências: O líder codifica as dependências das tarefas durante a decomposição. A camada de coordenação as aplica, para que nenhum agent comece antes que seus pré-requisitos sejam cumpridos, sem sondagem manual.
Como equipes de agents funcionam na prática
Uma equipe de agents é composta pelos seguintes componentes, cada um com uma função específica:
O líder da equipe é a sessão principal do Claude Code. Ele cria a equipe, instancia colegas, coordena o trabalho entre eles e sintetiza o resultado final. Esta é a sessão com a qual você interage diretamente.
Colegas são instâncias separadas do Claude Code, cada uma trabalhando de forma independente nas tarefas atribuídas dentro de sua própria janela de contexto. Eles não compartilham contexto com o líder nem entre si; a comunicação acontece explicitamente, pela lista de tarefas e pela caixa de mensagens.
A lista de tarefas compartilhada e a caixa de mensagens viabilizam a coordenação**.** A lista de tarefas compartilhada é uma fila ativa que o grupo de agents lê e atualiza. O líder a preenche no momento da decomposição, e os colegas assumem tarefas, trabalham nelas e as marcam como concluídas. As dependências são aplicadas automaticamente; quando um colega conclui uma tarefa, quaisquer tarefas bloqueadas por ela são desbloqueadas sem intervenção manual. A caixa de mensagens é o sistema de troca de mensagens para comunicação direta entre agents. As mensagens fluem automaticamente entre os colegas e o líder.
Tanto a configuração da equipe quanto a lista de tarefas são armazenadas localmente (~/.claude/teams/ e ~/.claude/tasks/). O Claude Code gera e mantém esses arquivos automaticamente. Não os edite manualmente, pois quaisquer alterações serão sobrescritas na próxima atualização de estado.
Como configurar equipes de agents no Claude Code
Equipes de agents do Claude vêm desativadas por padrão no Claude Code. Elas são marcadas como experimentais e exigem adesão explícita. Veja o caminho completo de configuração. Antes de ativar equipes de agents, confirme se sua versão do Claude Code é v2.1.32 ou posterior**.** Você pode executar claude --version no terminal para verificar.
Etapa 1: Ative a feature flag
Defina a variável de ambiente CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS como 1. Há três formas de fazer isso:
Opção A: ~/.claude/settings.json (recomendado)
Opção B: perfil do shell (~/.bashrc ou ~/.zshrc)
Opção C: inline, para uma única sessão
Se você editou settings.json ou seu perfil do shell, reinicie o Claude Code para que a flag entre em vigor.
Etapa 2: Instale tmux (recomendado, mas não obrigatório)
Equipes de agents são exibidas em dois modos: in-process (todos os colegas rodam dentro do terminal principal) e painéis divididos (cada colega tem seu próprio painel, o que requer tmux ou iTerm2). Executar cada colega em seu próprio painel de terminal facilita muito o monitoramento da equipe em tempo real.
Para garantir que você permaneça no modo de painéis divididos, defina teammateMode em ~/.claude/settings.json:
Para substituir a configuração padrão "auto", defina teammateMode em ~/.claude/settings.json como in-process. Para forçar o modo in-process em uma única sessão, passe-o como flag: claude --teammate-mode in-process.
Etapa 3: Use um prompt para iniciar sua equipe de agents
Depois de ativar a equipe de agents, basta dizer ao Claude, em linguagem natural, quais tarefas, entregável e estrutura de equipe você quer que a equipe de agents execute. Você pode especificar cada função no prompt, e o Claude criará a equipe, instanciará os colegas e agendará as tarefas de acordo.
Exemplo de prompt:
Você pode especificar qual modelo suas equipes de agents usarão, como "Use Sonnet for every teammate". Os colegas não herdam o modelo do agent líder. Os usuários devem especificar o modelo no frontmatter do arquivo de função ou definir um modelo padrão para colegas via /config.
Etapa 4: Peça aprovação do plano para tarefas complexas (opcional)
Para tarefas de alto risco e complexidade, você pode exigir que a equipe elabore um plano antes da execução. Os colegas do grupo de agents trabalharão em modo somente leitura, e o líder revisará, ajustará e, por fim, aprovará o plano. Somente quando o plano for aprovado pelo líder os colegas começarão a implementar.
Observe que o agent líder tomará as decisões; por isso, você também pode fornecer alguns critérios de decisão.
Exemplo de prompt:
Etapa 5: Configure git worktrees para isolamento de arquivos (opcional, recomendado)
Se algum colega escrever arquivos, Claude Code worktrees são altamente recomendados. Um git worktree é um diretório de trabalho separado em seu próprio branch, compartilhando o mesmo histórico .git do seu checkout principal. Cada agent recebe acesso isolado aos arquivos, e edições em um worktree nunca tocam no trabalho em andamento de outro agent.
Para ativar isso por agent, basta adicionar isolation: worktree ao frontmatter YAML do agent. O Claude Code provisiona um worktree novo para cada invocação paralela de agent e o limpa automaticamente quando o agent termina.
Para uso na CLI: claude --worktree ou claude -w inicia uma sessão em seu próprio worktree. O app desktop cria automaticamente um Claude Code worktree por sessão.
Etapa 6: Monitore em intervalos regulares
Equipes de agents não são algo para configurar e esquecer, e equipes de longa duração podem se desviar do objetivo. Agents podem ficar presos em prompts de permissão, marcar tarefas como concluídas cedo demais ou perder o escopo de vista. Você pode verificar a cada 10–15 minutos e revisar a lista de tarefas compartilhada em busca de tarefas travadas ou não assumidas. Se uma tarefa não avançar em 20–30 minutos, pode ser por bloqueio de permissão ou por uma função mal especificada que exige intervenção manual.
Comparação lado a lado: subagents vs equipes de agents
Subagents seguem um padrão de delegação. Equipes de agents seguem um padrão de colaboração. A diferença afeta tudo, de como o contexto é gerenciado a quanto custa uma execução.
| Subagents | Equipes de agents | |
|---|---|---|
| Comunicação | Unidirecional: o líder despacha, os subagents reportam de volta | Ponto a ponto + coordenação do líder |
| Estado compartilhado | Nenhum | Lista de tarefas compartilhada com rastreamento de dependências |
| Janelas de contexto | Janela de contexto própria; os resultados voltam para o líder | Cada colega tem a sua (até 1M tokens) |
| Prevenção de conflitos de arquivo | Não integrado | Bloqueio de arquivos incluído |
| Custo de token | Menor | Maior (cada colega é uma instância única) |
| Retomada de sessão | Compatível | /resume and /rewind don't restore in-process teammates |
| Agents aninhados | Compatível | Não compatível; somente o líder pode instanciar colegas |
| Indicado para | Delegação focada, fluxos de trabalho repetíveis | Trabalho paralelizável, interdependente e multidomínio |
Subagents seguem um padrão de delegação unidirecional: o líder envia uma tarefa, o subagent a executa dentro da própria janela de contexto, e o resultado é devolvido. Não há estado compartilhado, comunicação direta entre agents irmãos nem camada de coordenação — apenas um ciclo limpo de despacho e retorno.
Equipes de agents trabalham sobre uma lista de tarefas compartilhada, com aplicação automática de dependências, e trocam mensagens ponto a ponto entre colegas pela caixa de correio.
Em resumo, equipes de agents valem a pena quando o trabalho se divide em trilhas paralelas realmente independentes que precisam compartilhar descobertas e se coordenar. Para resultados rápidos, tarefas sequenciais, edições em um único arquivo ou qualquer cenário em que a previsibilidade de custo pese mais que a velocidade, subagents são a melhor escolha.
Quando escolher equipes de agents e quando escolher subagents
Use equipes de agents quando:
Os colegas precisam se comunicar diretamente entre si
O trabalho exige uma lista de tarefas compartilhada com rastreamento de dependências entre fluxos paralelos
A tarefa é grande demais para uma única sessão, e cada trabalhador precisa de um contexto próprio totalmente independente
Use subagents quando:
Você só precisa do resumo final, não de toda a saída intermediária
O trabalho é autocontido o bastante para retornar um resultado limpo
Você quer restringir ferramentas ou direcionar para um modelo mais barato
Você precisa de caminhos de pesquisa paralelos que não dependem uns dos outros
Se você não consegue identificar pelo menos três fluxos paralelos realmente independentes, uma única sessão ou subagents provavelmente superarão uma equipe de agents com custo menor.
Casos de uso reais para equipes de agents
Quando o trabalho se divide naturalmente em fluxos bem delimitados, esses fluxos podem avançar sem esperar uns pelos outros (ou suas dependências podem ser codificadas explicitamente), e o custo de coordenação é pequeno em relação ao tempo economizado pela execução em paralelo. Veja cinco casos de uso em que equipes de agents superam uma única sessão.
Revisão de código em paralelo
Atribua três revisores simultaneamente a um pull request, incluindo um agent de segurança, um agent de desempenho e um agent de cobertura de testes. O líder sintetiza os três relatórios paralelos em uma única lista de ações priorizada. Esse padrão também funciona para revisão de arquitetura (agent de escalabilidade, agent de segurança, agent de manutenibilidade) ou verificações de conformidade em diferentes marcos regulatórios.
Depuração por hipóteses concorrentes
Instancie cinco agents, cada um com uma única hipótese, para testar arquivos ou logs específicos e investigar um bug em produção. O primeiro agent que confirmar sua hipótese apresenta a correção, e os demais podem ser interrompidos. É uma forma mais eficiente do que investigar cada teoria em sequência, gastar horas depurando um caminho, voltar atrás e começar o próximo.
Refatorações entre camadas
Uma tarefa de refatoração entre camadas contém etapas sequenciais e paralelas. Por exemplo, uma mudança incompatível na API exige atualizações nos endpoints de backend, nos componentes de frontend que consomem esses endpoints e na suíte de testes que cobre ambos. O trabalho de backend precisa ser concluído antes que o frontend possa começar. Assim que a tarefa de backend estiver em andamento, o agent da suíte de testes pode começar a estruturar em paralelo a nova arquitetura de testes. Em uma equipe de agents, o líder usa o rastreamento de dependências da lista de tarefas compartilhada para codificar essa ordem.
Varredura de pesquisa sem contaminação de contexto
Uma decisão técnica pode exigir a análise de vários conjuntos independentes de evidências, como escolher um mecanismo de banco de dados, avaliar três APIs de terceiros e examinar ferramentas de build. Atribua a cada agent um domínio sem sobreposição, e cada um publica um resumo estruturado. O líder agrega tudo em um documento comparativo. O isolamento preserva uma perspectiva independente, melhorando a qualidade dos resultados.
Migração de uma grande base de código
Atualizar uma dependência importante em uma grande base de código normalmente envolve alterar vários módulos. Se esses módulos têm limites claros e podem migrar simultaneamente, equipes de agents ajudam. Atribua um agent a cada módulo independente; cada agent migra seu módulo, executa sua própria suíte de testes e retorna com um resumo da migração que inclui quaisquer interfaces alteradas. O líder revisa as mudanças de interface antes de declarar a migração concluída e coordena a sequência de merge.
O que fazer e evitar ao projetar sua equipe de agents
Criar um sistema de agents paralelos com Claude Code é simples de configurar, mas fácil de fazer errado. Estes são os princípios de design que determinam se sua equipe de agents entrega resultado ou apenas perde tempo.
Dicas avançadas para criar seu sistema de agents paralelos
Pré-aprove permissões: Os colegas começam com as configurações de permissão do líder. Se o líder roda com --dangerously-skip-permissions, todos os colegas também herdam isso. Você pode ajustar os modos individuais dos colegas depois de instanciá-los, mas não é possível configurar modos por colega no momento da instanciação. Planeje sua postura de permissões pelo líder antes de lançar a equipe.
Escreva prompts de papel bem enxutos: Cada prompt de papel deve especificar quatro pontos: o que fazer, em quais arquivos ou domínios trabalhar, no que focar e o que excluir, e como deve ser o entregável. Ao instanciar colegas, você pode referenciar tipos de subagent de qualquer escopo de subagent: projeto, usuário, plugin ou definido pela CLI. Isso permite definir um papel uma vez, como revisor de segurança ou executor de testes, e reutilizá-lo tanto como subagent delegado quanto como colega em uma equipe de agents.
Imponha isolamento de arquivos: Para qualquer agent que escreva em disco, use isolamento. Dois agents modificando o mesmo arquivo simultaneamente é uma das formas mais certeiras de produzir saída corrompida.
Acompanhe em intervalos regulares: A cada 10–15 minutos em equipes de agents ativas. Verifique na lista de tarefas compartilhada se há tarefas paradas. Uma tarefa travada por mais de 20–30 minutos pode indicar problema de permissão, papel mal especificado ou dependência circular, o que pode exigir resolução manual.
Codifique dependências explicitamente: Se a Tarefa B vem logicamente depois da Tarefa A, registre essa dependência na lista de tarefas durante a decomposição, não como instrução em um prompt de papel. A camada de coordenação aplica dependências automaticamente; instruções em prompts podem ser mal interpretadas ou ignoradas.
Defina limites de propriedade no seu arquivo md: Em projetos com múltiplas sessões, escreva uma regra determinando que cada módulo ou diretório tenha exatamente um agent responsável. Isso evita sobreposição antes mesmo de a equipe ser lançada.
Sempre faça a limpeza pelo líder, não por um colega: O líder verifica se há colegas ativos antes de liberar recursos. Colegas não têm o contexto completo da equipe para limpar tudo com segurança; fazer isso pode deixar a sessão em um estado inconsistente.
Erros comuns que você pode evitar na sua equipe de agents
Não instancie uma equipe para uma tarefa que uma única sessão resolve bem: Antes de escrever um único arquivo de papel ou enviar um único prompt de swarm, desenhe o grafo da tarefa. Quais subtarefas são realmente independentes? Quais têm dependências? É um trabalho com dependência sequencial? Se você não consegue articular três trilhas paralelas com limites claros, uma única sessão terá desempenho melhor que a equipe.
Não atribua dois agents ao mesmo arquivo. Essa é a fonte mais comum de conflitos de merge e sobrescritas silenciosas. Se a decomposição da sua tarefa gera dois agents que precisam mexer no mesmo componente, o trabalho nesse componente deve ser sequencial — atribua-o a um agent depois que o outro concluir.
Não pule a pré-aprovação de permissões no Claude Code. Prompts de permissão que aparecem no meio da execução interrompem o paralelismo e exigem intervenção manual. Essa sobrecarga elimina boa parte do benefício. Pré-aprove gravações de arquivos e comandos de shell no diretório de trabalho antes de iniciar.
Não espere restaurar sua equipe do Claude Code. Se uma sessão for limpa, /resume e /rewind não restauram colegas em execução in-process. Salve saídas intermediárias importantes antes de execuções longas.
Não passe de cinco integrantes sem um motivo claro. Os custos de token crescem linearmente, mas a sobrecarga de coordenação cresce mais rápido. Três agents focados, com papéis bem definidos, superam de forma consistente cinco agents com papéis vagos. Adicione colegas apenas quando houver um fluxo paralelo explícito aguardando — não porque “mais” pareça melhor.
Outro paradigma: crie sua equipe multi-agent no Kimi Agent Swarm
Equipes de agents do Claude Code se destacam em cenários nativos para desenvolvedores, com integração profunda aos fluxos de terminal e ao ecossistema Git. No entanto, o paradigma de colaboração multi-agent vai muito além da linha de comando. O Kimi Agent Swarm é onde esse paradigma se torna acessível a todos.
Kimi Agent Swarm é o sistema de colaboração multi-agent da Kimi, criado para tarefas complexas e de grande escala. Ele divide um objetivo amplo em subtarefas discretas e agenda diferentes agents e habilidades para lidar simultaneamente com busca, leitura, análise, escrita, codificação, geração de planilhas, criação de slides e construção de páginas web. Sem flags de env. Sem exigir config de git.
Principais recursos do Kimi Agent Swarm
Colaboração paralela com até 300 sub-agents: Kimi Agent Swarm decompõe uma tarefa complexa e agenda múltiplos sub-agents para lidar com subtarefas simultaneamente. O sistema consegue coordenar até 300 sub-agents para executar mais de 4.000 chamadas de ferramentas em uma única execução.
Execução composta multi-habilidade: O Swarm consegue combinar várias habilidades especializadas em uma única execução, incluindo pesquisa aprofundada, pptx, redação de relatórios, vibe-coding, criação de sites, escrita acadêmica, superando um único agent em profundidade de saída e cobertura de formatos.
Processamento documental em larga escala: Agent Swarm consegue processar arquivos em lote em mais de 20 formatos (PDF, Word, Excel, PPT, imagens etc.), lendo, extraindo informações e resumindo conteúdo em paralelo em todo o conjunto de documentos, com capacidade de referenciar bibliotecas, arquivos de inteligência competitiva ou ingestão de dados de múltiplas fontes.
Pesquisa ampla e proativa: Para tarefas que exigem informações em áreas extensas, Agent Swarm despacha sub-agents para pesquisar na web, localizar fontes, baixar conteúdo, categorizar descobertas e gerar resumos estruturados em paralelo.
Raciocínio multiperspectiva: Agent Swarm consegue executar simultaneamente vários pontos de vista especializados sobre o mesmo problema. Isso produz uma análise mais completa do que uma passagem com perspectiva única e revela pontos cegos que a revisão sequencial deixa passar.
Entrega de conteúdo em profundidade: A arquitetura paralela do Agent Swarm foi criada para saídas de profundidade sustentada, como relatórios de pesquisa com centenas de páginas, análises setoriais longas, revisões de literatura acadêmica, guias de aprendizagem estruturados e conteúdo narrativo extenso.
Saída multiformato em uma única execução: Agent Swarm consegue produzir simultaneamente vários tipos de entregáveis para a mesma tarefa, como um relatório em PDF, um deck em PPT, uma página web, um conjunto de dados em Excel e um projeto de código.
Como executar uma equipe de agents no Kimi Agent Swarm
Etapa 1: Abra o Kimi Agent Swarm e insira seu prompt
Abra a página do Agent Swarm e descreva sua tarefa na caixa de entrada. Para obter os melhores resultados, seja específico quanto ao escopo, aos entregáveis esperados e a quaisquer restrições, como período, fontes ou requisitos de formato.
Prompt de exemplo:
Etapa 2: Deixe o Kimi Agent Swarm trabalhar
Depois de enviar seu prompt, Agent Swarm dividirá a tarefa em subtarefas e despachará subagents para trabalhar em paralelo. Você pode acompanhar o progresso em tempo real, incluindo planejamento de tarefas, instanciação de sub-agents e execução paralela.
Etapa 3: Receba, visualize e baixe ou compartilhe os resultados
Quando a execução terminar, seus entregáveis estarão prontos para visualização diretamente na interface. Dependendo da tarefa, as saídas podem incluir relatórios de pesquisa, análises de dados, decks em PPT, páginas web, projetos de código ou uma combinação deles. Você pode baixar os arquivos e compartilhá-los diretamente.
Casos de uso em que o Kimi Agent Swarm se destaca
Redação de propostas e licitações: Atribua agents paralelos a especificações técnicas, requisitos de conformidade, modelos de precificação e estudos de caso simultaneamente; o orquestrador os integra em uma proposta coesa.
Análise financeira: Atribua agents paralelos para lidar com dados de mercado, documentos de concorrentes, indicadores macroeconômicos e modelos internos; o orquestrador os sintetiza em uma análise unificada.
Pesquisa de negócios: Atribua agents paralelos a cenários competitivos, entrevistas com clientes, relatórios setoriais e contexto regulatório de diferentes fontes; o orquestrador produz uma saída estruturada.
Testes de segurança: Execute agents paralelos para reconhecimento, varredura de vulnerabilidades, auditoria de dependências e verificações de escalonamento de privilégios; o orquestrador agrega as descobertas em um relatório final.
Desenvolvimento full-stack: Crie agents paralelos para componentes de frontend, endpoints de backend, esquema de banco de dados e suítes de testes; o orquestrador coordena a integração em toda a stack.
Conclusão
Equipes de agents do Claude Code são projetadas especificamente para fluxos de engenharia, levando execução paralela a bases de código complexas diretamente pelo terminal. Se seu trabalho vai além do código, o Kimi Agent Swarm leva o mesmo paradigma multi-agent a pesquisa, análise, conteúdo e muito mais. Basta descrever sua tarefa e deixar o swarm cuidar do resto.