Orquestração de agentes de código: quando 1 agente não basta

Um agente sozinho resolve bem: “corrija esse teste”, “extraia esse componente”, “escreva o endpoint”. Ele falha quando a tarefa vira grafo: pesquisa + implementação + review + QA, ou três abordagens concorrentes no mesmo bug. Orquestração é o nome chato para uma ideia simples — dividir trabalho, isolar estado, esperar conclusão, integrar — aplicada a agentes de código.

Este artigo cobre quando vale orquestrar, um modelo mental (coordenador / workers / gates) e um fluxo prático sem vender magia.


Quando 1 agente não basta

Sinais de que você está forçando um único loop:

  • O prompt mistura papéis (“implemente e revise e atualize o changelog”).
  • Dois arquivos grandes mudam em direções opostas e o agente “oscila”.
  • Você quer comparar soluções (race) em vez de aceitar a primeira.
  • Há dependência real: B só começa depois que A entrega um contrato.
  • O working tree está sujo e dois agentes brigam pelo mesmo git status.

Se a tarefa cabe em um PR pequeno e um contexto claro, não orquestre. Orquestração tem custo de setup, de tokens e de atenção humana.


Modelo mental: Run, Task, Worker

Ferramentas como Orca formalizam algo que times improvisavam com tmux + worktrees:

ConceitoFunção
RunNamespace da iniciativa (“split checkout QA”) — inbox do coordenador
TaskUnidade de trabalho com spec, status e dependências
Dispatch / WorkerUma tentativa de executar a task num terminal/agente
Decision gatePergunta que bloqueia até um humano (ou política) decidir
worker_doneSinal de conclusão — o coordenador só integra com evidência

O coordenador não precisa ser um modelo genial. Precisa ser previsível: criar tasks, escolher agentes, esperar, rejeitar lixo, abrir PR.

Para o mapa de ferramentas (Cursor, Claude Code, OpenCode, Orca), veja a comparação.


Padrões que funcionam

1. Pipeline (A → B → C)

Exemplo: “migrar auth”.

  1. Worker A: inventário de call sites + riscos.
  2. Gate: humano aprova escopo.
  3. Worker B: implementação no worktree.
  4. Worker C: só review (read-only) no diff.
  5. Coordenador: merge local / PR.

Cada etapa tem uma definição de pronto. Evite “faça tudo e me avise”.

2. Fan-out / fan-in

Exemplo: “three fixes independentes no monorepo”.

  • Três tasks ready sem dependência.
  • Três worktrees, três agentes (podem ser o mesmo produto, sessões isoladas).
  • Fan-in: só integra quem passou nos testes da pasta dela.

3. Race (mesmo prompt, N agentes)

Fluxo clássico do Orca:

  1. Três worktrees a partir do mesmo ref.
  2. Claude Code / Codex / Cursor CLI com o mesmo prompt.
  3. Comparar diffs; anotar o vencedor; apagar os outros.

Onde os três concordam, a resposta tende a ser segura. Onde divergem, você achou a parte difícil — e isso é o valor, não um bug do processo.

4. Especialista + executor

  • Agente “pesquisador” (docs, MCP, codebase map) produz um brief curto.
  • Agente “implementador” recebe só o brief + constraints.
  • Evita um único contexto inchado que esquece a metade do pedido.

Exemplo de loop supervisionado (conceitual)

Pseudofluxo alinhado a CLIs de orquestração modernas:

# 1) Criar a iniciativa
orca orchestration run-create --objective "Isolar e corrigir flaky e2e de checkout" --json

# 2) Tasks com specs curtas e testáveis
orca orchestration task-create --task-title "Reproduzir flake" --spec "..." --json
orca orchestration task-create --task-title "Corrigir causa raiz" --spec "..." --json

# 3) Worker em worktree novo (não no tree sujo do humano)
orca orchestration worker-start \
  --task <taskId> \
  --worktree new-child \
  --name flake-repro \
  --agent claude \
  --setup run \
  --json

Nomes de flags variam por versão — o importante é a disciplina: objetivo → tasks → worker isolado → done → integração.

Para o isolamento em si, leia Git worktrees + agentes em paralelo.


O que o coordenador deve exigir no “done”

Sem isso, orquestração vira teatro:

  • Comando de verificação rodado (teste, typecheck, lint do pacote tocado).
  • Lista do que não foi feito.
  • Diff limitado ao escopo (sem “aproveitei e reformatei o monorepo”).
  • Segredos: nenhum .env commitado.
  • Links para artefatos (log, screenshot) quando UI estiver no escopo.

Skills e rules ajudam a padronizar esse contrato — Skills e Rules para agentes.


Anti-padrões

  • Orquestrar por moda: três agentes para um typo.
  • Shared dirty tree: dois writers no mesmo checkout.
  • Prompt novel: 80 linhas de contexto irrelevante.
  • Sem gate humano em decisões de produto/API pública.
  • Integrar sem ler o diff porque “o agente disse que passou”.

Checklist

  • A tarefa é grafo ou race — não um ticket linear?
  • Cada worker tem um worktree ou sandbox?
  • Definição de pronto cabe em 3 bullets?
  • Há um único dono da integração?
  • MCP/tools necessários estão no worker certo — não em todos?

Conclusão

Orquestração de agentes de código não é “mais IA”. É processo de engenharia com isolamento e contratos. Use quando o trabalho paralelo ou o pipeline justificarem o overhead; caso contrário, um bom agente + boas rules ainda vence.

Se quiser ver o perfil e os projetos por trás destes textos: portfolio.