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:
| Conceito | Função |
|---|---|
| Run | Namespace da iniciativa (“split checkout QA”) — inbox do coordenador |
| Task | Unidade de trabalho com spec, status e dependências |
| Dispatch / Worker | Uma tentativa de executar a task num terminal/agente |
| Decision gate | Pergunta que bloqueia até um humano (ou política) decidir |
| worker_done | Sinal 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”.
- Worker A: inventário de call sites + riscos.
- Gate: humano aprova escopo.
- Worker B: implementação no worktree.
- Worker C: só review (read-only) no diff.
- 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
readysem 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:
- Três worktrees a partir do mesmo ref.
- Claude Code / Codex / Cursor CLI com o mesmo prompt.
- 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
.envcommitado. - 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.