# Orchestrate Agents

> 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).

- Skill: `jezweb/orchestrate-agents` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jezweb/orchestrate-agents`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jezweb/orchestrate-agents/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: jezweb (https://skillmd.com/u/jezweb)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jezweb/orchestrate-agents

---


# 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.
- **When an agent writes into a file a human also owns, give it one block, not the whole file.** A naive append duplicates sections; a naive overwrite destroys the human's work; asking the model to regenerate the merged file is slow and drifts (a full rewrite of a large record times out and silently truncates). Instead the agent maintains a single delimited block it owns (`<!-- agent:mined start … end -->`) and rewrites *only* that block each run, appending it once if absent. Every other byte is preserved deterministically, at any file size — the human owns the file, the agent owns its block. The file-level form of "code owns structure, the model owns judgment" (`write-prompts`): never have a model reproduce a large artifact it could instead edit in place.
- **Compute identity in code; model "same-as" as an edge, not a merge.** Ask a model to mint a record id and three models give three ids for the same input — identity must be derived deterministically (a slug from the domain, a hash of source-id + timestamp) so a re-run upserts instead of duplicating. When two records turn out to be the same entity, link them with an explicit alias / same-as edge rather than silently merging: the merge is lossy and unreviewable, the edge is neither. Another instance of code owning structure while the model owns the judgment of *whether* they're the same.
- **An agent free to file needs a basis for restraint.** Agents file reflexively, and reflexive filing is how a knowledge corpus drowns — the same completion pressure that makes a model fill an empty slot (`write-prompts`) makes it keep every scrap it extracts. The discriminator isn't "is this true or useful" but "does *this* owner or purpose need it to operate?", judged against an owner/task profile the agent reads on wake; noise stays in an inbox rather than getting filed. And don't crystallise a recurring observation into durable knowledge until it has actually recurred (≈3×) — graduate on repetition, not on first sighting.

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.