Multi-agent and orchestration

Marta has a guest house (alojamento local) in Calheta and three texts on her website: “Quartos” (Rooms), “Como chegar” (How to get here) and “Regras da casa” (House rules). They were written at different times. One addresses the guest as “você” (formal), another as “tu” (informal), and the third talks about “os senhores hóspedes” (very formal, “the gentlemen guests”). She wants to review the three and make them speak with the same voice.

You can ask a single agent to do this. Or you can have three review at the same time and a fourth unify the tone. This lesson is about learning to choose.

The concept: when it is worth it

Several agents pay off when:

• the work splits into independent parts (three texts, three modules);
• each part fills the context with things you will not see again, and you only care about the conclusion;
• you want different roles: whoever writes should not be whoever reviews.

They do not pay off when the task is small, when all of them would have to touch the same files, or when you are not yet sure what you want. In that case, one agent and a good request (lesson 2/01) are enough.

Three patterns cover almost everything:

• Chaining: the result of one is the input of the next. First find the problems, then fix them.
• Parallelising: independent parts run at the same time and someone merges at the end.
• Plan, execute, review: one makes the plan, another executes, and a third (or you) checks the result against the plan.

How it is done today: subagents in Claude Code

This is how it looks on 6 October 2026; your screen may differ. Look for the button with the same name. Guide: code.claude.com/docs/en/sub-agents.

A subagent is a Markdown file in .claude/agents/ (this project only) or in ~/.claude/agents/ (all your projects). At the top it carries name and description, both required, and it can carry tools and model. Create .claude/agents/revisor-texto.md (“text-reviewer”):

---
name: revisor-texto
description: Reviews a website text in European Portuguese and returns problems and a corrected version
tools: Read, Glob, Grep
model: inherit
---

You are a reviewer of texts in European Portuguese. Read the given file and return:
1. a short list of problems (mistakes, long sentences, inconsistent form of address);
2. a corrected version, without changing facts, prices or opening times.
Do not edit files.

With read-only tools, the reviewer cannot save anything. model: inherit uses the same model as the session; you can choose a smaller one to save money, as you saw in lesson 2/06.

You call a subagent by name, in a normal request, or with @agent-revisor-texto. Marta's full example:

Use three revisor-texto subagents in parallel, one for each file:
textos/quartos.md, textos/como-chegar.md and textos/regras.md.
Wait for all three. Then, based on the three reviews, propose a final version
of each text with the same tone: address the guest as «tu», short sentences,
without changing opening times or prices. Show me the diff before saving.

Notice the design: three reviewers read in parallel, a single agent (the main one) merges and writes, and you approve the diff.

In Codex: subagents or a script

Codex also launches subagents when you ask for them directly, or when an instruction in the project tells it to. They inherit the session's sandbox, and /agent lets you see them and switch between them while they work. Guide: learn.chatgpt.com/docs/agent-configuration/subagents.

Launch one subagent per file to review textos/quartos.md, textos/como-chegar.md
and textos/regras.md in European Portuguese. The subagents only read and propose.
Wait for all three and then unify the tone of the three versions, without changing facts.
Show me the diff before saving.

For agents you reuse, Codex accepts TOML files in .codex/agents/, with name, description and developer_instructions.

You can also orchestrate yourself, in a script. codex exec reads the text you pass it on standard input as context and writes only the final answer:

mkdir -p revisoes
for f in quartos como-chegar regras; do
  codex exec "Review this text in European Portuguese: list the problems and propose a corrected version, without changing facts." \
    < textos/$f.md > revisoes/$f.md &
done
wait

The & puts each review running in the background; wait waits for all three. By default, codex exec can only read, and it needs to be inside a Git repository.

Measure before you multiply

• In Claude Code, /usage shows the tokens and an estimated cost for the session.
• With claude -p "…" --output-format json, the answer carries the total_cost_usd field.
• With codex exec --json, the turn.completed event carries the tokens used.