| name | orchestrate-agents |
| description | Use when deciding how to arrange agents for a piece of work: one agent or several, which pattern (single loop, pipeline, routing, parallel, orchestrator-workers, evaluator loop, triage funnel), how to match roles to model temperaments, how to bound a model-driven control loop so it's safe to trust instead of hand-coding a deterministic spine, and the mechanics that keep multi-agent work safe and cheap. The layer above agent-delegation (one-off hand-offs) and run-a-role-agent (one ongoing role). |
Orchestrate agents: pick the arrangement, then the models
Multi-agent is a cost you pay, not a virtue you collect. The default is one capable agent in a tool loop; every additional agent adds coordination, latency, and new failure modes. Escalate to an arrangement only when at least one of these is true:
- the task has independent subtasks that can genuinely run in parallel
- tool noise is polluting the main agent's judgment (long tool transcripts degrade decisions; a worker can absorb them and return a conclusion)
- cost per iteration is high and most of the work doesn't need the big model
- the work needs persistent memory in one place while the doing stays stateless
The arrangements
The first five follow Anthropic's taxonomy (their "Building Effective Agents" is the canonical read); the sixth keeps earning its place in fleet work:
| Pattern | One line | Reach for it when | Skip it when |
|---|
| Single loop | One model, tools, it decides when to stop | Most tasks; steps can't be pre-decomposed | The task is fixed-shape (write a script) |
| Pipeline | A → B → C with checkpoints | Clean sequential stages (draft → translate → format) | Stages need to talk backwards |
| Routing | A classifier sends input to one of N handlers | Heterogeneous inputs needing structurally different handling | Categories aren't crisp; misrouting is silent |
| Parallel | Independent calls at once; aggregate or vote | Speed (independent sections) or confidence (multiple perspectives on an uncertain answer) | Hidden dependencies between the calls |
| Orchestrator-workers | One agent decomposes and dispatches focused workers, then synthesises | Subtasks aren't known until inspection; tool noise needs absorbing | Small tasks (ceremony exceeds work) |
| Triage funnel | Cheap sweep detects, escalates only flags to a judgment model | High-volume recurring work where most items are routine | Every item genuinely needs judgment |
The funnel deserves emphasis because it answers the cost question most fleets get wrong: don't run the smart model over everything daily — run a cheap compliant model that detects change, and spend judgment only on what it flags. Typically 5-10× cheaper AND better, because the strong model sees only interesting input.
Roles match temperaments
Models differ on two axes that matter more than size for agentic work (see write-prompts): judgment (questions its inputs) vs compliance (does exactly as told). Every temperament has a home:
| Role | Temperament | Prompt style | Tools |
|---|
| Orchestrator | Judgment | Goal-oriented; identity primes effort ("you are the X orchestrator" reads differently from "process this record") | Plan, dispatch, synthesise, write results — not the raw data tools |
| Worker / investigator | Cheap and diligent | Directive, tight scope, explicit output envelope | The actual MCP/data tools; read-only on shared state |
| Verifier | Compliant — here compliance is the virtue | Directive checklist against the worker's output | Read-only on what the worker did |
Anything where the input might be wrong wants a judgment model — a compliant one executes a wrong instruction perfectly and corrupts your records without a sound. Price is not a proxy for temperament: cheap models can be diligent, premium ones obedient. Bake off on your task with a deliberate flaw planted in the input to see who notices, and re-run when the model landscape shifts.
Running the control loop as an agent — bound it, don't avoid it
The strongest form of "reach for the agent first" (plan-and-build) is letting the loop itself decide what to read, when to fan out, and what to write — instead of a hand-coded spine that polls, packs context, and pre-scripts the map-reduce. The objection is real: an unbounded loop wanders and burns tokens. But the answer is a fenced loop, not a deterministic spine — you keep the agent's judgment about which inputs matter and when to stop, which a fixed pipeline can't give you.
- Fence the failure you observe, don't pre-fence the loop. It's tempting to make a loop "safe" by bolting the whole kit on up front — a step cap, a no-progress budget, per-turn tool scoping, approval gates, a finish tool, a tool whitelist. Resist it: build minimal-first here too (
write-prompts). Start from the bare pattern and add a fence only when inspection shows the specific failure it cures — it wandered → step cap; it wrote to scratch space → scope that tool; it never stopped → no-progress budget; it can act destructively or outward → approval gate. Much of that control machinery turns out to compensate for a cluttered tool surface, not a model weakness; strip the surface first, and a capable model on a clean one often needs almost none of it. The fences that do earn their place bound the loop's freedom without pre-deciding it. (A managed harness — Claude Code as a library, the Agents SDK Think class — provides these as primitives when you need them; reach for it before hand-rolling durability, polling, and context-packing.)
- Migrate the spine, keep the brain. Moving from hand-coded control to a loop (or a harness that provides one) changes only the execution plumbing: the detached-run polling, the context-packing, the rigid pipeline. Everything that carried judgment ports over unchanged — the prompts, the doctrine, the write conventions, the role identities. If the migration tempts you to rewrite the prompts too, you've mistaken the spine for the brain. Rebuild the spine; port the brain.
Mechanics that earned their place
- Parallel dispatch is free wall-clock. An orchestrator that emits three dispatches in one turn waits only for the slowest. The most underused lever in the pattern; strong orchestrators parallelise on their own, weaker ones need telling.
- Iteration caps are safety rails, not behaviour tuning. Tight caps (8, 15) cut workers off mid-investigation and return "unknown" before convergence. Set them generous (50+); the model's own decision to stop is the natural exit.
- Let the orchestrator self-serve cheap reads, dispatch the bulk. Reading known state itself is fine; anything that pulls volumes of live external data into its context re-imports the tool-noise problem workers exist to solve.
- Worker contracts: one bounded output, no interim narration, hard checkpoints. The loop-safety rules in
run-a-self-refining-loop apply to every dispatched worker.
- Two prompts that are each fine can fail at the interface. One real fleet had an orchestrator gating confidence per-field while its investigator reported it per-envelope — each prompt correct alone, and a seven-fact answer got one rating. Audit the contract between agents (names, units, granularity), not just each prompt; granularity mismatches degrade both sides silently.
- The first write to shared state is the boundary; cross it in shadow mode. Everything before an agent's first write to live shared state is reversible; after it, propagated. Run it writing to a quarantine path first (same work, parked output), read that output at volume, then graduate writes from low-stakes records upward — and hold outputs that trigger other agents (briefs, messages) behind a gate until their acceptance rate earns release.
- Verify by reading outputs, not aggregates. A run that confidently did the wrong thing produces the same green stats as one that did the right thing; the difference only shows when you (or a verifier) read what it actually wrote. And when an agent "isn't doing X", check it isn't doing X a different way before you "fix" it — your instrument often measures the tool you expected it to use, not the raw one it actually used.
- Agents outside your harness don't inherit your briefs. A Claude Code session auto-loads the workspace CLAUDE.md cascade; an API-called or Worker-hosted agent gets nothing unless you assemble those briefs into its system prompt per task. Without that, it hallucinates your conventions. The brief assembly is the onboarding. Diagnostic corollary: when a separate agent fails plausibly-but-wrong — a confabulated file path, an assumed convention, a made-up fact — suspect unrealised context before you suspect a bad prompt or a missing tool. A capable model papers over an absence convincingly, so missing context wears the costume of a prompt bug, and the local dev is structurally the worst-placed to notice (the context it forgot to transmit is ambient to it — the water it swims in). The off-machine agent is the honest mirror: it shows how much of "works great locally" was the environment, not the prompt.
Pair with agent-delegation (should this be an agent at all, or a script?), run-a-role-agent (one ongoing role), run-a-self-refining-loop (the loop mechanics), and write-prompts (prompt style × temperament). The failure this prevents: a fleet of agents that costs ten times what the work needs, an orchestrator drowning in tool output, a compliant model silently corrupting records that a $0.05 diligent one would have flagged — or multi-agent ceremony wrapped around a task one good agent would have just done.
