Paralelizar somente o trabalho separável

Uma equipe quer adicionar aprovação de ordens de manutenção integradas ao ERP. Alguém propõe cinco agentes: gerente, arquiteto, programador, testador e revisor. Todos recebem o mesmo repositório, a mesma descrição vaga e permissão para editar. O “arquiteto” muda o contrato; o “programador” implementa a versão anterior; o “testador” escreve testes para uma terceira interpretação. O gerente gasta mais tempo conciliando resultados do que uma execução focada gastaria fazendo o trabalho.

O número de personagens não criou paralelismo útil. Apenas multiplicou decisões sobre o mesmo estado.

Vocabulário antes da orquestra

Concorrência é organizar vários trabalhos que progridem em períodos sobrepostos; eles podem alternar num único recurso. Paralelismo é executar trabalhos simultaneamente. A distinção é clássica em computação e aparece claramente no material oficial de Go: concorrência trata de lidar com muitas coisas; paralelismo, de fazer muitas coisas ao mesmo tempo.

Um subagente é um trabalhador delegado para uma tarefa focada, geralmente em contexto próprio, que devolve resultado ao chamador. Um sistema multiagente contém vários agentes com alguma coordenação: um orquestrador, uma lista compartilhada, mensagens ou handoffs. Um sistema multiagente pode ser inteiramente sequencial; dois agentes em paralelo podem não formar uma equipe que conversa.

Multiplicação de agentes é a antipadrão: várias instâncias recebem o mesmo trabalho sem partição, independência ou regra de integração. Votação entre cópias pode ser uma técnica de amostragem em um experimento, mas não substitui decomposição nem transforma respostas correlacionadas em avaliação independente.

Situação	Nome correto	Benefício possível
agente pesquisa API enquanto outro pesquisa autenticação	paralelismo com subagentes	reduz tempo e isola ruído
agente de implementação termina antes do testador começar	pipeline sequencial multiagente	especialização, não velocidade simultânea
três agentes editam o mesmo endpoint	multiplicação conflitante	normalmente nenhum
um agente alterna entre chamadas enquanto aguarda rede	concorrência	melhor uso do tempo de espera

Separabilidade é uma propriedade do trabalho

Uma tarefa tende a ser separável quando possui:

• entrada e saída delimitadas;
• poucas dependências ainda abertas;
• pouco estado mutável compartilhado;
• ownership de arquivos ou recursos não sobreposto;
• critério de conclusão verificável;
• valor em contexto próprio, sem reler toda a conversa;
• integração mais barata que o trabalho economizado.

Pesquisa por fontes independentes, execução de suítes distintas, triagem de logs e revisão somente leitura são bons candidatos. Uma mudança pequena no mesmo componente, uma migração cuja decisão ainda está aberta ou uma correção que exige ciclos rápidos entre código e teste tende a permanecer com um agente.

Mesmo grandes janelas de contexto não eliminam o problema. A documentação atual do Codex recomenda começar subagentes por tarefas intensivas em leitura e ter cuidado com escrita paralela. Contexto isolado preserva a conversa principal de logs e exploração volumosa, mas o trabalhador não conhece automaticamente todas as decisões. A delegação deve fornecer o mínimo suficiente; o retorno deve comprimir evidência sem inventar certeza.

Dependências formam um grafo, não uma lista de desejos

Represente cada trabalho como nó; uma seta indica “precisa terminar antes”. Se não houver ciclos, temos um grafo acíclico dirigido, ou DAG. A frontier executável é o conjunto de tarefas abertas cujas dependências já foram satisfeitas.

No projeto de manutenção:

A frontier inicial é {REQ, AUTH, ERP}. Esses trabalhos são somente leitura e podem avançar em paralelo. IMPL permanece bloqueada até receber os três artefatos. Depois de IMPL, teste e avaliação podem progredir juntos se não editarem a mesma fronteira. RELEASE espera ambos.

O caminho crítico é a cadeia de maior duração que determina o menor tempo possível. Adicionar agentes fora da frontier não encurta esse caminho. Se IMPL leva quatro horas e não pode ser dividida com segurança, dez trabalhadores aguardando não a tornam instantânea.

Em sistemas distribuídos, o fan-out também herda a cauda: uma junção que exige todas as respostas pode esperar pelo trabalhador mais lento. O artigo primário The Tail at Scale explica como episódios raros de alta latência passam a dominar sistemas grandes. Para agentes, defina timeout, resposta parcial aceitável e se a tarefa lenta será cancelada, retomada ou isolada.

Contrato de delegação: o briefing que governa

“Revise tudo e faça o necessário” não é delegação governável. Use:

id: AUTH
objective: verificar autorização de approveOrder contra SPEC-014
scope: [services/api, packages/domain]
mode: read-only
inputs: [docs/specs/SPEC-014.md, diff atual]
output: findings/auth.json
evidence: caminho, linha, impacto e reprodução por achado
forbidden: [editar, chamar produção, inferir requisito ausente]
budget: {minutes: 20, tool_calls: 30, tokens: 18000}
stop: critérios revisados ou bloqueio documentado
on_failure: uma repetição para erro transitório; depois bloquear IMPL

O contrato delimita objetivo, entrada, autoridade, saída, orçamento e parada. A documentação atual do Claude Code permite configurar ferramentas e permissões de subagentes; a ideia geral independe do produto: um filho não precisa herdar todas as credenciais do coordenador.

Handoff não é despejar conversa

No sentido geral desta obra, handoff transfere estado vivo para a próxima etapa:

{
  "task": "AUTH",
  "status": "complete",
  "artifacts": ["findings/auth.json"],
  "decisions": [],
  "evidence": ["TEST-AUTH-NEG falha antes da correção"],
  "unresolved": ["regra para supervisor temporário"],
  "next": "IMPL pode começar após REQ e ERP"
}

Referencie artefatos existentes; não cole toda a trajetória. Um resumo sem evidência transfere alegação. Uma transcrição integral transfere ruído, possíveis segredos e prompt injection.

No OpenAI Agents SDK, handoff também é um mecanismo específico no qual um agente transfere o controle da conversa a um especialista; agents as tools mantém o gerente no controle. A documentação permite filtrar o histórico entregue e tipar metadados do handoff. Não confunda essa API de roteamento com o artefato editorial acima, embora ambos precisem de contrato e observabilidade.

Ownership de escrita e merge

Dois agentes não devem escrever simultaneamente o mesmo arquivo, schema, migração ou contrato sem um protocolo explícito. “O Git resolve” é falso: Git pode marcar conflito textual, mas não detecta duas mudanças semanticamente incompatíveis em arquivos diferentes.

Reduza conflito com:

1. tarefas somente leitura sempre que possível;
2. ownership exclusivo por arquivo ou capacidade;
3. interfaces estabilizadas antes da implementação paralela;
4. worktree ou sandbox separado por escritor;
5. commits pequenos com artefato de saída;
6. integrador único que compara tudo com a especificação;
7. testes de contrato e integração após o merge.

Frontend, API e testes não são automaticamente independentes: todos podem depender do mesmo contrato ainda instável. Primeiro produza um tracer bullet ou contrato aceito; só então distribua implementações. Para migrações amplas, expand–migrate–contract pode criar fases compatíveis e diminuir a região de conflito.

Avaliação independente não é confirmação social

O avaliador recebe a especificação, o artefato e uma rubrica. Não recebe primeiro a defesa persuasiva do autor. Ele opera preferencialmente em modo somente leitura e tenta falsificar propriedades: papel incorreto recebe 403? retry duplica baixa? estado muda após negação?

autor → artefato + evidência ─┐
spec → critérios ─────────────┼→ avaliador independente → achados
justificativa do autor ───────┘ (somente depois da inspeção inicial)

Independência é relativa. Dois agentes do mesmo modelo podem compartilhar pontos cegos; um avaliador automatizado pode ser ancorado pela mesma documentação. Combine testes determinísticos, modelos ou prompts distintos quando justificado e revisão humana proporcional ao impacto. Divergência é resolvida por evidência e contrato, não por maioria de agentes.

Budgets e stop conditions evitam loops caros

Todo worker e o sistema inteiro precisam de limites:

• máximo de agentes simultâneos e total de delegações;
• tokens, custo, tempo, turnos e chamadas de ferramenta;
• profundidade de delegação ou proibição de recursão;
• caminhos graváveis, rede, egress e credenciais;
• quantidade de retries e backoff;
• tamanho do retorno ao coordenador.

Uma stop condition observável encerra em sucesso, bloqueio, orçamento, ausência de progresso, cancelamento ou risco que exige humano. “Pare quando achar suficiente” pode ser parte de uma heurística de pesquisa, mas precisa de teto externo. Um worker que repete a mesma consulta sem novo resultado deve parar antes de gastar todo o orçamento.

Budgets hierárquicos evitam que cada filho considere possuir o total. Se o sistema dispõe de 100 mil tokens, o coordenador reserva integração e distribui parcelas; não promete 100 mil a cada agente.

Tracing: reconstruir o que aconteceu

Logs soltos não explicam uma execução distribuída. Um trace correlaciona o trabalho completo; spans representam agente, turno, ferramenta ou handoff. A documentação atual do OpenAI Agents SDK registra spans para agentes, gerações, ferramentas, guardrails e handoffs, incluindo uso de tokens em níveis de tarefa e turno.

Registre, com política de privacidade:

trace_id, parent_span_id, task_id, agent_id, attempt,
started_at, ended_at, status, model/tool, tokens, cost,
artifact_refs, error_class, stop_reason

Trace precisa responder: quem delegou? qual frontier existia? que entrada foi usada? qual tentativa falhou? que artefato venceu? por que parou? Não grave prompt integral, segredo ou dado pessoal por padrão. Use IDs e referências com controle de acesso e retenção.

Falha parcial é o estado normal

Num conjunto de três trabalhadores, um pode falhar enquanto dois terminam. O coordenador decide por tarefa:

• obrigatória: falha bloqueia dependentes;
• opcional: resultado parcial segue com limitação explícita;
• retryable: erro transitório repete com chave e limite;
• fatal: autorização negada ou contrato inválido não é resolvido repetindo;
• compensável: efeito já aplicado exige ação de correção, não simples rollback imaginário.

Checkpoint e artefatos duráveis permitem retomar sem refazer pesquisa cara. Retry de ações precisa de idempotência. Resultado atrasado deve carregar versão da entrada; caso contrário, um worker “zumbi” pode sobrescrever decisão mais nova. O coordenador deve conseguir cancelar, ignorar resultado obsoleto e fechar workers órfãos.

Estado atual: produto não é princípio universal

Fotografia em 2026-08-09:

• Codex documenta subagent workflows atuais, com custo adicional de tokens, e aconselha cautela em escrita paralela;
• Claude Code documenta subagentes estáveis, enquanto agent teams permanecem experimentais e desativadas por padrão na versão documentada 2.1.178, com limitações de coordenação e shutdown;
• OpenAI Agents SDK oferece managers, agents-as-tools, handoffs e tracing; são padrões de orquestração de aplicação, não prova de que vários agentes são necessários.

Antes, demonstrações tratavam “equipe de agentes” como sinal de maturidade. Agora, a recomendação fundamentada continua: workflow simples primeiro, complexidade apenas onde o trabalho e as evals a justificam. Um produto pode mudar seu botão ou comando; dependência, ownership, budget e evidência permanecem.

Era Maestro: uma promoção conquistada por eval

Nesta obra, Era Maestro é a metáfora para uma pessoa governar vários agentes e integrações. Não é certificação nem recurso universal. A promoção ocorre em degraus:

agente único → subagente focado → paralelismo por frontier
→ avaliador independente → coordenação multiagente

Preserve um baseline de agente único. Rode o mesmo conjunto congelado e um holdout não usado no ajuste. Meça qualidade de resultado, tempo de relógio, tokens/custo, conflitos, retrabalho, permissões, falhas e revisão humana. A Anthropic publicou um ganho de 90,2% em sua eval interna de pesquisa e também informou que o sistema multiagente consumia cerca de 15 vezes os tokens de chat. Esses números explicam aquele sistema de pesquisa, não prometem ganho para programação.

Multiagente vence quando o valor da amplitude, independência ou tempo economizado supera custo e risco. Se três agentes custam quatro vezes mais, criam dois conflitos e não melhoram holdout, a decisão correta é voltar ao desenho simples.

Laboratório executável: valide o grafo antes de convocar agentes

Objetivo: provar que somente a frontier é delegável e detectar ciclo, contrato incompleto, conflito de escrita, avaliador contaminado e ausência de limites. Hipótese: um manifesto pequeno impede erros estruturais antes de qualquer chamada de modelo. Ambiente: Python 3.10+, biblioteca padrão, sem rede ou segredos. Duração: 45 a 60 minutos.

Salve como orchestration_guard.py:

from __future__ import annotations

import json
import sys
from pathlib import Path


BAD = {
    "policy": {"max_agents": 0, "max_total_tokens": 0, "max_recursion": -1},
    "trace_fields": ["trace_id", "task_id", "status"],
    "tasks": [
        {"id": "A", "objective": "", "deps": ["B"], "mode": "write",
         "write_paths": ["services/api/order.py"], "output": "a.json",
         "stop": "", "budget_tokens": 0, "on_failure": ""},
        {"id": "B", "objective": "build B", "deps": ["A"], "mode": "write",
         "write_paths": ["services/api/other.py"], "output": "b.json",
         "stop": "done", "budget_tokens": 1000, "on_failure": "block"},
        {"id": "C", "objective": "edit order", "deps": [], "mode": "write",
         "write_paths": ["services/api/order.py"], "output": "c.diff",
         "stop": "done", "budget_tokens": 1000, "on_failure": "block"},
        {"id": "D", "objective": "also edit order", "deps": [], "mode": "write",
         "write_paths": ["services/api/order.py"], "output": "d.diff",
         "stop": "done", "budget_tokens": 1000, "on_failure": "block"},
        {"id": "E", "objective": "evaluate", "deps": [], "mode": "write",
         "role": "evaluator", "author_context": True, "rubric": "",
         "write_paths": ["services/api/order.py"], "output": "review.json",
         "stop": "done", "budget_tokens": 1000, "on_failure": "block"},
    ],
}


GOOD = {
    "policy": {"max_agents": 3, "max_total_tokens": 120000, "max_recursion": 0},
    "trace_fields": [
        "trace_id", "parent_span_id", "task_id", "agent_id", "attempt",
        "started_at", "ended_at", "status", "tokens", "cost", "error",
    ],
    "tasks": [
        {"id": "REQ", "objective": "confirm requirements", "deps": [],
         "mode": "read", "write_paths": [], "output": "requirements.json",
         "stop": "artifact or blocker", "budget_tokens": 12000, "on_failure": "block"},
        {"id": "AUTH", "objective": "audit authorization", "deps": [],
         "mode": "read", "write_paths": [], "output": "auth-findings.json",
         "stop": "artifact or blocker", "budget_tokens": 12000, "on_failure": "block"},
        {"id": "ERP", "objective": "inspect ERP contract", "deps": [],
         "mode": "read", "write_paths": [], "output": "erp-contract.json",
         "stop": "artifact or blocker", "budget_tokens": 12000,
         "on_failure": "retry_once_then_block"},
        {"id": "IMPL", "objective": "implement approved contract",
         "deps": ["REQ", "AUTH", "ERP"], "mode": "write",
         "write_paths": ["services/api/order.py"], "output": "implementation.diff",
         "stop": "tests prepared or blocker", "budget_tokens": 24000, "on_failure": "block"},
        {"id": "TEST", "objective": "run deterministic tests", "deps": ["IMPL"],
         "mode": "read", "write_paths": [], "output": "test-results.json",
         "stop": "results recorded", "budget_tokens": 10000, "on_failure": "block"},
        {"id": "EVAL", "objective": "independent spec review", "deps": ["IMPL", "REQ"],
         "mode": "read", "role": "evaluator", "author_context": False,
         "rubric": "SPEC-014 acceptance criteria", "write_paths": [],
         "output": "eval-findings.json", "stop": "rubric complete or blocker",
         "budget_tokens": 14000, "on_failure": "block"},
        {"id": "RELEASE", "objective": "integrate verified artifacts",
         "deps": ["TEST", "EVAL"], "mode": "write",
         "write_paths": ["release/manifest.json"], "output": "release-evidence.json",
         "stop": "evidence complete", "budget_tokens": 8000, "on_failure": "block"},
    ],
}


def dependency_closure(task_id: str, by_id: dict[str, dict]) -> set[str]:
    seen: set[str] = set()
    stack = list(by_id[task_id].get("deps", []))
    while stack:
        current = stack.pop()
        if current in seen or current not in by_id:
            continue
        seen.add(current)
        stack.extend(by_id[current].get("deps", []))
    return seen


def waves(plan: dict) -> tuple[list[list[str]], set[str]]:
    by_id = {task["id"]: task for task in plan.get("tasks", [])}
    done: set[str] = set()
    result: list[list[str]] = []
    while len(done) < len(by_id):
        ready = sorted(
            task_id for task_id, task in by_id.items()
            if task_id not in done and set(task.get("deps", [])) <= done
        )
        if not ready:
            return result, set(by_id) - done
        result.append(ready)
        done.update(ready)
    return result, set()


def validate(plan: dict) -> list[str]:
    findings: set[str] = set()
    policy = plan.get("policy", {})
    if (policy.get("max_agents", 0) <= 0 or policy.get("max_total_tokens", 0) <= 0
            or policy.get("max_recursion", -1) < 0):
        findings.add("PLAN:invalid-budgets")

    required_trace = {"trace_id", "parent_span_id", "task_id", "agent_id", "attempt",
                      "started_at", "ended_at", "status", "tokens", "cost", "error"}
    if not required_trace <= set(plan.get("trace_fields", [])):
        findings.add("PLAN:incomplete-tracing")

    tasks = plan.get("tasks", [])
    by_id = {task.get("id"): task for task in tasks}
    if len(by_id) != len(tasks) or None in by_id:
        findings.add("PLAN:duplicate-or-missing-id")
    for task_id, task in by_id.items():
        if any(dep not in by_id or dep == task_id for dep in task.get("deps", [])):
            findings.add(f"{task_id}:invalid-dependency")
        if not task.get("objective") or not task.get("output") or not task.get("stop"):
            findings.add(f"{task_id}:incomplete-contract")
        if task.get("budget_tokens", 0) <= 0:
            findings.add(f"{task_id}:invalid-budget")
        if not task.get("on_failure"):
            findings.add(f"{task_id}:missing-failure-policy")
        if task.get("role") == "evaluator":
            if (task.get("mode") != "read" or task.get("author_context") is not False
                    or not task.get("rubric")):
                findings.add(f"{task_id}:evaluator-not-independent")

    schedule, blocked = waves(plan)
    if blocked:
        findings.add("PLAN:cycle-or-unreachable-tasks")

    ids = sorted(by_id)
    for index, left_id in enumerate(ids):
        for right_id in ids[index + 1:]:
            left, right = by_id[left_id], by_id[right_id]
            ordered = (left_id in dependency_closure(right_id, by_id)
                       or right_id in dependency_closure(left_id, by_id))
            overlap = set(left.get("write_paths", [])) & set(right.get("write_paths", []))
            if overlap and not ordered:
                findings.add(f"{left_id}+{right_id}:parallel-write-conflict")
    return sorted(findings)


def simulate(plan: dict) -> dict:
    schedule, blocked = waves(plan)
    assert not blocked
    events = []
    completed = []
    for wave_number, frontier in enumerate(schedule):
        assert len(frontier) <= plan["policy"]["max_agents"] or wave_number > 0
        for task_id in frontier:
            if task_id == "ERP":
                events.append({"task": task_id, "attempt": 1, "status": "transient_failure"})
                events.append({"task": task_id, "attempt": 2, "status": "complete"})
            else:
                events.append({"task": task_id, "attempt": 1, "status": "complete"})
            completed.append(task_id)
    return {
        "valid": True,
        "initial_frontier": schedule[0],
        "waves": schedule,
        "partial_failure": {"task": "ERP", "recovered_on_attempt": 2},
        "completed": completed,
        "release_unblocked": completed[-1] == "RELEASE",
    }


def main() -> int:
    mode = sys.argv[1] if len(sys.argv) > 1 else "prove"
    if mode == "bad":
        findings = validate(BAD)
        print(json.dumps({"valid": False, "findings": findings}, indent=2))
        assert "PLAN:cycle-or-unreachable-tasks" in findings
        assert "C+D:parallel-write-conflict" in findings
        assert "E:evaluator-not-independent" in findings
        return 2
    if mode == "prove":
        findings = validate(GOOD)
        assert findings == [], findings
        evidence = simulate(GOOD)
        assert evidence["initial_frontier"] == ["AUTH", "ERP", "REQ"]
        assert evidence["waves"] == [
            ["AUTH", "ERP", "REQ"], ["IMPL"], ["EVAL", "TEST"], ["RELEASE"]
        ]
        output = Path("orchestration-output") / "evidence.json"
        output.parent.mkdir(exist_ok=True)
        output.write_text(json.dumps(evidence, indent=2), encoding="utf-8")
        print(json.dumps(evidence, indent=2))
        print(f"evidence={output}")
        return 0
    print("usage: python orchestration_guard.py [bad|prove]", file=sys.stderr)
    return 64


if __name__ == "__main__":
    raise SystemExit(main())

O script é um simulador didático, não executa agentes nem estima preço real. Ele valida estrutura e gera evidência determinística.

Execute:

python orchestration_guard.py bad
# esperado: exit 2; ciclo, conflito C+D, avaliador contaminado e limites ausentes

python orchestration_guard.py prove
# esperado: exit 0; quatro ondas, retry do ERP e release desbloqueado

Get-Content -LiteralPath .\orchestration-output\evidence.json

Como diagnosticar a falha provocada

• A ↔ B cria ciclo: nenhuma delas pode entrar na frontier;
• C e D podem executar juntas e escrevem o mesmo caminho: ownership inválido;
• E edita, recebe contexto do autor e não possui rubrica: não é avaliador independente;
• A não tem objetivo, parada, budget ou política de falha: delegação ingovernável;
• o plano não possui budgets válidos nem campos de tracing suficientes.

Na versão corrigida, três investigações começam juntas, IMPL espera seus contratos, EVAL e TEST avançam após a implementação, e RELEASE fecha o grafo. A falha transitória simulada do ERP usa uma única repetição e preserva a dependência; erro fatal deveria bloquear em vez de repetir indefinidamente.

Critérios de aceite

• toda tarefa possui objetivo, escopo, entrada, saída, budget, parada e política de falha;
• a frontier é calculada por dependências concluídas, não por prioridade subjetiva;
• nenhuma dupla potencialmente concorrente escreve o mesmo caminho ou recurso;
• contexto isolado recebe somente decisões e referências necessárias;
• handoffs apontam para artefatos e registram lacunas;
• avaliador começa por spec, artefato e rubrica, em modo somente leitura;
• retry é limitado e idempotente; falha parcial bloqueia apenas dependentes necessários;
• trace correlaciona agentes, tentativas, ferramentas, handoffs, custo e stop reason;
• baseline e holdout medem ganho líquido antes da Era Maestro;
• bad retorna 2, prove retorna 0 e evidence.json mostra quatro ondas.

Exercícios e recuperação ativa

1. Adicione DOCS sem dependências e somente leitura. Em qual frontier entra?
2. Faça TEST também escrever services/api/order.py. Preveja o conflito antes de executar.
3. Torne ERP opcional. Defina como IMPL declara limitação sem fingir que o contrato foi validado.
4. Modele um resultado atrasado da versão 1 chegando após a versão 2. Inclua versão no handoff e descarte o zumbi.
5. Compare o mesmo trabalho com um agente, três subagentes e equipe multiagente em dez casos congelados e cinco holdouts. Registre tempo, tokens, acerto, conflitos e revisão humana.
6. Dê ao avaliador a justificativa do autor antes da spec e observe se seus achados mudam. Isso mede risco de ancoragem, não independência perfeita.

Sem consultar, explique a diferença entre concorrência e paralelismo; calcule a frontier inicial; diga por que três agentes no mesmo arquivo não encurtam o caminho crítico; descreva um handoff verificável; e liste as evidências que autorizariam a Era Maestro.

Limpeza e conclusão

Remova somente os artefatos criados na pasta descartável do laboratório:

Remove-Item -LiteralPath .\orchestration-output -Recurse
Remove-Item -LiteralPath .\orchestration_guard.py

Confirme o caminho antes de executar. Preserve a evidência se ela fizer parte de uma avaliação formal.

O maestro competente não tenta fazer todos tocarem o tempo inteiro. Ele conhece partitura, dependências, entradas, pausas e condição de encerramento. Em engenharia de agentes, isso significa paralelizar somente a frontier, isolar escrita, limitar autoridade, observar falhas e aceitar o sistema simples quando as evals mostram que ele é melhor.