Multi-Agent Orchestration Patterns

Q: When is multi-agent orchestration worth the overhead?

When a task needs decomposition (a feature touching DB, API, UI, and tests) or one context can't hold all relevant files. For a single-file edit or one-shot task, one agent is faster — orchestration adds latency and failure modes for no gain.

Q: What topology should I use: pipeline, loop, or fan-out?

Pipeline (planner, coder, reviewer) is simplest and works for most tasks. Add a loop (coder and reviewer until approve) for self-correction. Use fan-out (N independent coders plus merge) for parallelizable independent steps. Start with pipeline.

Q: How do agents share context without shared memory?

Serialize every handoff as a JSON file. The planner's step list becomes the coder's input; the coder's diff becomes the reviewer's input. Each agent starts with a clean context reading only its input file — no implicit shared state.

Q: How do I stop the reviewer agent from rubber-stamping?

Give it concrete, checkable reject criteria ('reject if the diff adds unrequested files, uses banned patterns, or fails any acceptance criterion') and require an explicit APPROVE/REJECT with reasons. A vague 'is this good?' reviewer approves everything and defeats the gate.

Q: What if the coder and reviewer loop forever?

Cap every loop at 3 iterations and escalate to a human on exhaustion. Log the full transcript per step so the disagreement is debuggable. Infinite loops usually mean the spec is ambiguous or the reviewer's criteria conflict with the coder's constraints.

Coordinate multiple AI agents (planner, coder, reviewer) for tasks too big for one context.

Agent DevelopmentAdvanced

Why

MCP's reference server repo has ~90,000 GitHub stars, and the Agentic AI Foundation grew from 49 founding members (December 2025) to 247 by August 2026, signaling rapid multi-agent ecosystem growth. A single agent hits context limits and loses the plot on big tasks.

Splitting work across specialized agents (planner decomposes, coder implements, reviewer critiques) keeps each context focused, produces better-reasoned output, and lets the loop self-correct without a human in every cycle. This is how you scale AI beyond a single prompt.

When

Orchestrate multiple agents when a task needs decomposition (a feature touching DB, API, UI, and tests), when one context cannot hold all relevant files, or when you want a built-in reviewer to gate the coder. Avoid it for tasks a single agent handles in one shot; the orchestration overhead is not worth it.

How

1. Decompose the task into roles with clear handoffs: Planner: reads spec, outputs a step list with file targets. Coder: takes one step, implements it, runs the gate. Reviewer: diffs the coder's output against the step, approves or rejects. 2. Choose an orchestration topology: - Pipeline: planner -> coder -> reviewer, linear, simplest. - Loop: coder -> reviewer -> coder until reviewer approves. - Fan-out: planner splits into N independent coder runs, then merge. 3. Pass context explicitly between agents, never implicitly: - Planner output (step list) is the coder's input. - Coder output (diff + gate result) is the reviewer's input. - Serialize handoffs as JSON files so each agent starts clean. 4. Run the coder with a scoped context (only the files for that step): claude --scope src/api/ "implement step 3: POST /api/books" 5. Gate with the reviewer agent, not just tests: "Review this diff against the step spec. Reject if it adds unrequested files, uses banned patterns, or fails any acceptance criterion. Output APPROVE or REJECT + reasons." 6. Loop on REJECT: feed the reviewer's reasons back to the coder as the next prompt. Cap the loop at 3 iterations; beyond that, escalate to a human. 7. Merge approved steps and run the full gate: npm run check && npm test && npm run build Commit the merged result with a summary of the agent run.

Example

Pipeline orchestration with JSON handoffs (Node.js driver): // 1. Planner const plan = await runAgent({ role: "planner", prompt: "Decompose 'add books hub' into steps with file targets. Output JSON.", }); // plan = [{ step: 1, target: "src/data/books.ts", task: "add Books type + CRUD" }, ...] // 2. Coder + Reviewer loop per step for (const s of plan) { let verdict = "REJECT", tries = 0; while (verdict === "REJECT" && tries < 3) { const diff = await runAgent({ role: "coder", scope: s.target, input: s }); verdict = await runAgent({ role: "reviewer", input: { s, diff } }); if (verdict.startsWith("REJECT")) s = { ...s, feedback: verdict }; tries++; } if (verdict.startsWith("REJECT")) throw new Error(`step ${s.step} failed review`); await commit(diff); } // 3. Final gate await run("npm run check && npm test && npm run build");

Common Problems

⚠Error: Agent loops infinitely on the same tool call → add a max-iterations guard and a distinctness check on the last N actions.
⚠Error: Cannot find module '@modelcontextprotocol/sdk' → `npm install @modelcontextprotocol/sdk`; agents need the SDK to call MCP tools.
⚠Error: "Tool timed out after 30000ms" → increase the timeout config or break the task into smaller sub-tasks the agent can complete incrementally.
⚠Error: Agent loops infinitely on the same tool call → add a max-iterations guard and a distinctness check on the last N actions.

Best Practices

✓Define each role's input and output schema; serialize handoffs as JSON files.
✓Give the reviewer explicit, checkable reject criteria, not vague 'is this good' judgments.
✓Cap every loop (3 iterations) and escalate to a human on exhaustion.
✓Scope each coder run to only the files for its step to keep context focused.
✓Log the full agent transcript per step so failures are debuggable post-hoc.

FAQ

When is multi-agent orchestration worth the overhead?

When a task needs decomposition (a feature touching DB, API, UI, and tests) or one context can't hold all relevant files. For a single-file edit or one-shot task, one agent is faster — orchestration adds latency and failure modes for no gain.

What topology should I use: pipeline, loop, or fan-out?

Pipeline (planner, coder, reviewer) is simplest and works for most tasks. Add a loop (coder and reviewer until approve) for self-correction. Use fan-out (N independent coders plus merge) for parallelizable independent steps. Start with pipeline.

How do agents share context without shared memory?

Serialize every handoff as a JSON file. The planner's step list becomes the coder's input; the coder's diff becomes the reviewer's input. Each agent starts with a clean context reading only its input file — no implicit shared state.

How do I stop the reviewer agent from rubber-stamping?

Give it concrete, checkable reject criteria ('reject if the diff adds unrequested files, uses banned patterns, or fails any acceptance criterion') and require an explicit APPROVE/REJECT with reasons. A vague 'is this good?' reviewer approves everything and defeats the gate.

What if the coder and reviewer loop forever?

Cap every loop at 3 iterations and escalate to a human on exhaustion. Log the full transcript per step so the disagreement is debuggable. Infinite loops usually mean the spec is ambiguous or the reviewer's criteria conflict with the coder's constraints.