Multi-agente e orquestração

A Marta tem um alojamento local na Calheta e três textos no site: «Quartos», «Como chegar» e «Regras da casa». Foram escritos em alturas diferentes. Um trata o hóspede por «você», outro por «tu», e o terceiro fala de «os senhores hóspedes». Ela quer rever os três e pô-los a falar com a mesma voz.

Podes pedir isto a um só agente. Ou podes pôr três a rever ao mesmo tempo e um quarto a unir o tom. Esta lição é sobre saber escolher.

O conceito: quando vale a pena

Vários agentes compensam quando:

• o trabalho se divide em partes independentes (três textos, três módulos);
• cada parte enche o contexto com coisas que não vais voltar a ver, e só te interessa a conclusão;
• queres papéis diferentes: quem escreve não deve ser quem revê.

Não compensam quando a tarefa é pequena, quando todos teriam de mexer nos mesmos ficheiros, ou quando ainda não sabes bem o que queres. Nesse caso, um agente e um bom pedido (lição 2/01) chegam.

Três padrões cobrem quase tudo:

• Encadear: o resultado de um é a entrada do seguinte. Primeiro encontra os problemas, depois corrige-os.
• Paralelizar: partes independentes correm ao mesmo tempo e alguém junta no fim.
• Planear, executar, rever: um faz o plano, outro executa, e um terceiro (ou tu) confere o resultado com o plano.

Como se faz hoje: subagentes no Claude Code

Isto é como está a 6 de Outubro de 2026; se o ecrã for diferente, procura o botão com o mesmo nome. Guia: code.claude.com/docs/en/sub-agents.

Um subagente é um ficheiro Markdown em .claude/agents/ (só neste projecto) ou em ~/.claude/agents/ (em todos os teus projectos). No topo leva name e description, obrigatórios, e pode levar tools e model. Cria .claude/agents/revisor-texto.md:

---
name: revisor-texto
description: Revê um texto de site em português europeu e devolve problemas e uma versão corrigida
tools: Read, Glob, Grep
model: inherit
---

És revisor de textos em português europeu. Lê o ficheiro indicado e devolve:
1. uma lista curta de problemas (erros, frases longas, tratamento inconsistente);
2. uma versão corrigida, sem mudar factos, preços nem horários.
Não edites ficheiros.

Com tools só de leitura, o revisor não consegue gravar nada. O model: inherit usa o mesmo modelo da sessão; podes escolher um mais pequeno para poupar, como viste na lição 2/06.

Chamas um subagente pelo nome, num pedido normal, ou com @agent-revisor-texto. O exemplo completo da Marta:

Usa três subagentes revisor-texto em paralelo, um para cada ficheiro:
textos/quartos.md, textos/como-chegar.md e textos/regras.md.
Espera pelos três. Depois, com base nas três revisões, propõe uma versão final
de cada texto com o mesmo tom: tratamento por «tu», frases curtas,
sem mudar horários nem preços. Mostra-me o diff antes de gravar.

Repara no desenho: três revisores lêem em paralelo, um só agente (o principal) junta e escreve, e tu aprovas o diff.

No Codex: subagentes ou um script

O Codex também lança subagentes quando lhos pedes directamente, ou quando uma instrução do projecto o manda fazer. Herdam a sandbox da sessão e o /agent deixa-te ver e trocar entre eles enquanto trabalham. Guia: learn.chatgpt.com/docs/agent-configuration/subagents.

Lança um subagente por ficheiro para rever textos/quartos.md, textos/como-chegar.md
e textos/regras.md em português europeu. Os subagentes só lêem e propõem.
Espera pelos três e depois une o tom das três versões, sem mudar factos.
Mostra-me o diff antes de gravar.

Para agentes que reutilizas, o Codex aceita ficheiros TOML em .codex/agents/, com name, description e developer_instructions.

Também podes orquestrar tu, num script. O codex exec lê o texto que lhe passas pela entrada como contexto e escreve só a resposta final:

mkdir -p revisoes
for f in quartos como-chegar regras; do
  codex exec "Revê este texto em português europeu: lista os problemas e propõe uma versão corrigida, sem mudar factos." \
    < textos/$f.md > revisoes/$f.md &
done
wait

O & põe cada revisão a correr em fundo; o wait espera pelas três. Por omissão, o codex exec só lê, e precisa de estar dentro de um repositório Git.

Medir antes de multiplicar

• No Claude Code, o /usage mostra os tokens e um custo estimado da sessão.
• Com claude -p "…" --output-format json, a resposta traz o campo total_cost_usd.
• Com codex exec --json, o evento turn.completed traz os tokens usados.