Orquestrando múltiplos subagentes no Claude Code: construindo fluxos de trabalho complexos (2026)

- A superfície de orquestração de agentes no Claude Code muda rápido (times de agentes, fluxos de trabalho dinâmicos, limites de profundidade); os números aqui foram reconferidos com a documentação do Claude Code e o post de pesquisa da Anthropic no momento da escrita — verifique a documentação ao vivo antes de depender deles.

O que significa orquestrar subagentes?

Quando você já está confortável em criar e rodar um único subagente, o próximo passo é orquestrar subagentes no Claude Code: deixar um agente principal coordenar vários subagentes trabalhadores ao mesmo tempo, ou encadeá-los. Esse é o clássico padrão orquestrador-trabalhador (às vezes chamado de agente líder coordenando trabalhadores).

A definição curta para lembrar: orquestrar subagentes significa que um agente coordenador (o orquestrador) cria vários subagentes, cada um fazendo uma fatia do trabalho em sua própria janela de contexto separada, e então devolvendo um resumo enxuto para o agente principal combinar.

Todo o truque mora nessas duas palavras: "contexto separado". Cada subagente ganha uma janela de contexto independente, então pode ler dezenas de arquivos, rodar muitos comandos e produzir saídas longas sem inchar o contexto da sua sessão principal. O agente principal só recebe de volta a parte destilada. É assim que você encara uma tarefa grande e com vários ramos enquanto o contexto da sessão original continua limpo.

Isso é um recurso avançado. Se você ainda não tem clareza sobre o que é um subagente e como declarar um básico, leia primeiro o guia de subagentes para iniciantes e depois volte aqui. Este artigo pressupõe que você já criou pelo menos um subagente e agora quer dirigir vários de uma vez — algo que quase nenhum tutorial prático cobre de ponta a ponta.

Quando você DEVE e quando NÃO DEVE orquestrar vários subagentes

Coordenar vários agentes nem sempre é vantagem. Consome muitos tokens e adiciona latência, então só compensa quando a tarefa realmente se divide em ramos. Este é o ponto de decisão mais valioso, e é justamente a parte que a documentação e os blogs costumam pular.

O número de 15x em tokens e o alerta sobre estado compartilhado vêm ambos do post da Anthropic sobre o Multi-Agent Research System (13 de junho de 2025). Esse mesmo post observa que a maior parte da variação de desempenho (cerca de 80%) vem de quantos tokens são consumidos — ou seja, os tokens são tanto o custo quanto a alavanca. Regra pragmática: se você não consegue formular a tarefa como ramos claros e separados, não orquestre — use apenas uma sessão linear. Para ver onde os subagentes se encaixam em relação a skills, hooks e MCP, leia a diferença entre skills, subagentes, hooks e MCP.

Os dois padrões de orquestração: paralelo vs pipeline

Existem exatamente dois padrões fundamentais. Saber quando recorrer a cada um já te coloca à frente da maioria dos desenvolvedores.

Paralelo (fan-out / fan-in): o agente principal cria vários subagentes ao mesmo tempo, cada um cuidando de um ramo independente, e então o agente principal reúne (faz o fan-in) os resumos em um único resultado.

 ┌─→ subagent: auth ────┐
main agent ├─→ subagent: database ─┤─→ synthesize
 └─→ subagent: API ─────┘
 (parallel fan-out) (fan-in)

Pipeline (cadeia / sequencial): os subagentes rodam em ordem, onde a saída de um passo vira a entrada do próximo. O agente principal passa o contexto entre os elos.

main → subagent: reviewer → subagent: optimizer → result
 (find issues) (fix based on issues)

O teste de uma frase: se os ramos NÃO precisam saber os resultados uns dos outros, vá de paralelo; se o passo B precisa do resultado do passo A, vá de pipeline. Muitos fluxos reais são híbridos: faça o fan-out em paralelo durante uma fase de coleta e depois encadeie um passo final de síntese.

Exemplo 1 — Rodando subagentes EM PARALELO (do zero)

Uma tarefa real: você quer auditar rápido um repositório de backend, checando três áreas independentes de uma vez — auth, banco de dados e API. Essas três áreas não dependem umas das outras, o que as torna um encaixe de manual para execução em paralelo.

1. Digite o prompt coordenador. Peça ao Claude para fazer fan-out explicitamente, nomeie os três ramos e diga a cada subagente para devolver apenas um resumo:

   Audit this repo in parallel using 3 independent subagents:
   1) auth: check login flow, sessions, permission holes
   2) database: check schema, N+1 queries, missing indexes
   3) API: check input validation, rate limiting, error handling
   Each subagent should return only a short summary (~10 bullets max),
   NOT a full log dump. Then combine into one report.

2. Veja o Claude fazer o fan-out. O Claude Code cria os três subagentes para rodar em paralelo, cada um lendo o código em seu próprio contexto. Você vai ver três fluxos de trabalho rodando ao mesmo tempo na sessão.
3. Leia o resumo combinado. Quando os três terminam (fan-in), o agente principal os combina em um único relatório. Como cada subagente devolveu só tópicos enxutos, o contexto da sessão principal continua leve.

A saída condensada do passo de síntese fica mais ou menos assim (ilustrando o formato, não números reais do seu repositório):

Audit report (merged from 3 subagents):
[auth] - Sessions not setting HttpOnly/Secure flags
 - Missing permission check on /admin/* endpoints
[database] - Order list query has N+1 (findOne in loop)
 - users table missing index on email column
[API] - 4 endpoints not validating the request body
 - No rate limit on the login route

Por que o paralelo se encaixa aqui: os três ramos não precisam dos dados uns dos outros, então rodá-los em simultâneo reduz o tempo de relógio e isola cada relatório longo em seu próprio contexto. Forçar isso a rodar em sequência só deixaria mais lento, não mais correto.

Exemplo 2 — Um pipeline sequencial (cadeia): do reviewer ao optimizer

Uma tarefa real: você suspeita que um módulo tem problemas de desempenho. No passo 1, um subagente code-reviewer encontra os gargalos. No passo 2, um subagente optimizer os corrige com base nessa lista. Isso é uma dependência clara — o optimizer precisa saber o que o reviewer encontrou — então tem que ser sequencial, não paralelo.

1. Rode o reviewer primeiro. Prompt coordenador:

   Use the code-reviewer subagent to find performance bottlenecks
   in the src/services/ directory and return a prioritized list.

2. Passe o resultado ao optimizer. O agente principal pega a lista do reviewer como entrada para o próximo passo:

   Hand the list above to the optimizer subagent:
   fix in priority order, add one line explaining each change,
   and do NOT change any public API behavior.

3. Obtenha o resultado final. O optimizer trabalha exatamente no que o reviewer sinalizou. O Claude atua como o retransmissor, passando o contexto entre os dois elos.

[reviewer] Found 3 bottlenecks:
 P1 - parseAll() re-reads the file inside a loop
 P2 - sequential API calls that could be batched
 P3 - JSON.parse repeated on the same payload
[optimizer] Fixed:
 P1 → cache file contents outside the loop
 P2 → merge into a single batch request
 P3 → parse once, reuse the object

O ponto central: use um pipeline quando um passo posterior precisa da saída de um anterior. Se você tentasse paralelizar esses dois passos dependentes, o optimizer estaria corrigindo às cegas, porque a lista do reviewer ainda não existiria. A orquestração não vive isolada — é uma peça do fluxo de brainstorm a plan a cook a ship; normalmente você planeja primeiro e depois solta os subagentes para "cozinhar" os ramos.

Avançado — Agentes orquestradores, subagentes aninhados e limites de profundidade

Em vez de digitar um prompt coordenador toda vez, você pode declarar um agente orquestrador dedicado cuja única função é coordenar. Crie um arquivo em .claude/agents/coordinator.md:

---
name: coordinator
description: Coordinates worker subagents for large, multi-branch tasks.
 Only splits work, spawns workers, and merges summaries - does NOT write code itself.
---

You are a coordinating agent. Your job:
1. Decompose the request into independent branches (if any).
2. Independent branches → dispatch in parallel; dependent branches → chain.
3. Require each worker to return ONLY a tight summary.
4. Merge everything into a single result for the user.
Do not do the detailed work yourself; always delegate to workers.

O name e a description no frontmatter ajudam o Claude a saber quando chamar esse agente. A restrição de "só coordenar" o impede de entrar para fazer o trabalho sozinho e explodir seu próprio contexto.

Subagentes aninhados: um subagente pode criar seus próprios subagentes filhos. Isso é poderoso, mas fácil de perder o controle, então o Claude Code limita a profundidade. Segundo a documentação do Claude Code sobre subagentes (verificada em 2026-08), a profundidade padrão de criação é de 3 níveis e é ajustável pela variável de ambiente CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH. Configurá-la alto demais leva facilmente a uma explosão na contagem de agentes e a tokens queimados; a maioria dos fluxos reais nunca precisa passar do padrão.

Para tarefas paralelas duradouras ou que extrapolam uma única janela de contexto, dois primitivos nativos mais novos assumem onde este padrão para — veja "O que há de novo em orquestração (2026)" abaixo.

Além do modelo orquestrador-trabalhador, existe um padrão menos comum para quando você quer conselho em vez de execução delegada: o padrão consultivo: chamar o kongming para orientação em um checkpoint.

O que há de novo em orquestração (2026): fluxos de trabalho dinâmicos & times de agentes

O padrão prompt-e-coordenador coberto acima ainda funciona exatamente como descrito, e continua sendo o padrão certo para a delegação de rotina em vários ramos — a maioria das tarefas não precisa de mais do que isso. Desde que este guia foi publicado, o Claude Code lançou dois primitivos nativos mais novos que escalam a orquestração ainda mais: os fluxos de trabalho dinâmicos do Claude Code, em que o Claude escreve um script para distribuir o trabalho de forma programática, e os times de agentes do Claude Code, um modo experimental de múltiplas sessões. Nenhum substitui o padrão acima — eles se apoiam sobre ele para trabalhos maiores ou mais longos.

Mantenha o padrão prompt-e-coordenador acima para trabalho de rotina em vários ramos, como os dois exemplos deste guia. Recorra aos Fluxos de Trabalho Dinâmicos quando uma tarefa extrapolar uma janela de contexto ou se beneficiar de execução em segundo plano com verificação cruzada em escala real. Recorra aos Times de Agentes para uma configuração colaborativa de múltiplas sessões e longa duração, em vez de uma única rodada de delegar e receber de volta. Os dois primitivos ainda estão evoluindo, incluindo seus limites exatos de contagem de agentes e de concorrência, então reconfira a documentação ao vivo antes de depender de qualquer um deles em produção.

Otimizando tokens e custo quando você orquestra

Como as execuções multiagente custam cerca de 15x os tokens de uma sessão de chat comum (segundo a Anthropic), otimizar tokens não é opcional — é a condição que faz a orquestração valer o dinheiro. Alguns movimentos pragmáticos:

• Limite o número de subagentes a 3-5 por fan-out. Adicionar mais agentes raramente melhora a qualidade na mesma proporção, mas aumenta os tokens de forma linear.
• Direcione os trabalhadores para um modelo mais barato. Ramos simples (ler arquivos, listar coisas) podem ir para um modelo barato como o Haiku, reservando o modelo forte para o passo de síntese.
• Force os subagentes a devolver apenas resumos, não despejos completos de log/diff de volta ao agente principal. Essa é a maior fonte de tokens desperdiçados, e todo mundo cai nessa.
• Evite muitos subagentes devolvendo saídas longas ao principal — fazer o fan-in de várias saídas longas entope o contexto principal e anula todo o propósito do isolamento.

Para se aprofundar em orçamentos de tokens para sessões multiagente, veja o guia sobre otimizar tokens ao rodar muitos agentes.

Não quer construir você mesma? Um kit pronto de agente orquestrador (AgentKit)

Escrever um coordenador decente e um esquadrão de trabalhadores dá trabalho. Se você prefere ter algo pronto para usar, existe um kit que empacota tudo isso. Uma linha para evitar confusão: o AgentKit aqui é um kit para o Claude Code (agentkit.best, a CLI ak) — NÃO o AgentKit da OpenAI (Agent Builder/ChatKit, lançado em 6 de outubro de 2025).

O Engineer Kit do AgentKit vem com 17 agentes de engenharia (dos 45 totais da plataforma = 17 de engenharia + 28 de marketing) mais fluxos de orquestração — como a skill ak-orchestrate — para que você não precise escrever um coordenador do zero. O preço listado do Engineer Kit é US$ 99, e a página não menciona nenhuma cobrança recorrente. Sendo franca: você consegue perfeitamente construir um orquestrador sozinha seguindo as seções acima; o kit só vale a pena se você quiser economizar tempo de configuração e usar agentes pré-ajustados. Para ver exatamente o que há dentro, leia a análise do Engineer Kit, ou olhe direto os agentes orquestradores prontos do AgentKit.

Erros comuns ao orquestrar vários subagentes

• Criar subagentes demais. Quando todos devolvem resultados de uma vez, o contexto principal se esgota. Evite: mantenha 3-5 agentes por rodada e force resumos.
• Usar paralelo para trabalho dependente. Resultados errados ou condições de corrida. Evite: pergunte "o passo posterior precisa da saída do anterior?" — se sim, use um pipeline.
• Subagentes devolvendo logs longos em vez de resumos. Tokens desperdiçados e contexto entupido. Evite: declare os limites de saída explicitamente no prompt ou na definição do agente.
• Esquecer o limite de profundidade. Subagentes aninhados transbordam os níveis e a contagem de agentes explode. Evite: mantenha CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH no padrão a menos que tenha um motivo claro.
• Gasto desproporcional de tokens. Usar multiagente para uma mudança pequena. Evite: para tarefas pequenas ou rápidas, rode uma única sessão linear em vez de orquestrar.

Perguntas frequentes (FAQ)

Quantos subagentes podem rodar em paralelo?

Na prática, mantenha 3-5 subagentes por fan-out. Não é um limite rígido, mas mais do que isso normalmente não melhora a qualidade na mesma proporção, enquanto os tokens sobem rápido e o contexto combinado fica fácil de sobrecarregar. Várias rodadas pequenas de fan-out batem uma rodada gigante.

Paralelo ou pipeline custa mais tokens?

O paralelo normalmente dispara os tokens com mais força, porque muitos agentes rodam de uma vez, cada um com seu próprio contexto. Um pipeline consome tokens de forma mais moderada em qualquer instante isolado, mas acumula ao longo dos passos e é mais lento. Escolha com base nas dependências da tarefa, não só nos tokens.

Um subagente pode criar seus próprios subagentes filhos (aninhados)?

Sim. Um subagente pode criar subagentes filhos (subagentes aninhados). O Claude Code limita a profundidade — 3 níveis por padrão — e ela é ajustável pela variável CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH. A maioria dos fluxos nunca precisa passar do padrão.

Você precisa de times de agentes para orquestrar?

Não, não é obrigatório. Você pode orquestrar apenas com um prompt coordenador ou um agente orquestrador declarado por você. Times de agentes é uma superfície para paralelismo duradouro e de grande escala que extrapola uma única janela de contexto; confira a documentação ao vivo, já que o recurso é novo e muda rápido — veja "O que há de novo em orquestração (2026)" acima para a comparação completa.

Fluxos de Trabalho Dinâmicos é o mesmo que orquestrar subagentes?

Não. O padrão orquestrador-trabalhador deste guia é guiado por prompt — o Claude decide o que roda em seguida a cada turno. Fluxos de Trabalho Dinâmicos é um primitivo separado e mais novo: o Claude escreve um script JS de antemão, então o plano vive no script em vez do contexto do Claude, e ele pode distribuir para muito mais agentes (até 1.000, segundo a documentação no momento da escrita) do que você coordenaria à mão. Veja o guia completo de Fluxos de Trabalho Dinâmicos para configuração e limites.

Orquestrar vários agentes vale a pena para um projeto pequeno?

Normalmente não. Para mudanças pequenas ou rápidas, a coordenação e o custo em tokens (execuções multiagente custam cerca de 15x os tokens, segundo a Anthropic) superam o benefício. Só orquestre quando a tarefa realmente se divide em ramos independentes ou abrange muitas áreas.

Existe um kit pronto de agente coordenador?

Sim. O Engineer Kit do AgentKit (agentkit.best, a CLI ak — diferente do AgentKit da OpenAI) empacota 17 agentes de engenharia mais fluxos de orquestração, para que você não precise escrever um coordenador sozinha. Você ainda pode construir tudo por conta própria como mostrado acima; o kit só economiza tempo de configuração.

Conclusão e próximos passos

Não comece com uma orquestra de dez agentes. Construa primeiro um pipeline de dois passos (como reviewer para optimizer), meça os tokens que ele queima e só então expanda para o fan-out em paralelo quando a tarefa realmente se dividir em ramos independentes. Domine os fundamentos no guia de subagentes para iniciantes e coloque a orquestração no seu devido lugar dentro do fluxo de brainstorm a plan a cook a ship. Se você prefere não escrever um coordenador sozinha, dê uma olhada na análise do Engineer Kit.