Hitchhiker's Guide — Multi-Agent Orchestration

The compressed practitioner tour. If WARMUP.md is the professor, this is the senior who leans over and says "here's what you actually need to remember about multi-agent."

The 30-second mental model

A multi-agent system is several Phase-12 agents sharing a blackboard (authored, append-only state) and taking turns (a scheduler). It helps in exactly three cases — distinct roles, parallel subtasks, cross-checking — and is pure overhead otherwise. The best quality lever is the critique-revise loop (draft → critic → revise), which is dangerous precisely because it works: a critic that never accepts is a perfect infinite loop. So the real job is making it stop: max rounds, stall detection (no new progress → halt), and budgets. Default to one agent; multi-agent is an argument, not a reflex.

The numbers / rules to tattoo on your arm

ThingRule of thumb
When multi-agent helpsdistinct roles · parallel subtasks · cross-checking — else use one agent
Coordination costeach agent re-reads shared context as tokens every turn → ~agents × turns × ctx
Cheapest quality boostone critic turn often beats a bigger model
Critique-revise capalways cap (max_revisions); a never-accepting critic = infinite loop
Termination guardsmax rounds · stall detection · token/$ budget — all three, always
Voting helps ifferrors are independent; shared model/prompt/ctx → groupthink, vote hides it
Tie-breakdeterministic (earliest ballot), never max() over a dict
Schedule orderfixed list + cursor / sorted index — never set/dict iteration

Back-of-envelope one-liners

# "Should this be multi-agent?"
which of {distinct roles, parallel subtasks, cross-check} applies?  none → one agent + tools

# "Why is our agent system slow AND expensive?"
N agents × T turns × growing transcript = token bill;  scope each agent's context, cap T

# "It sometimes never finishes."
not a round-cap problem first — it's a STALL: same draft re-emitted, board not changing → detect & halt

# "Best-of-5 still hallucinates."
all 5 share the model+prompt+context → same bias → vote agrees on the same wrong answer (groupthink)

The framework one-liners (where these ideas live in real tools)

# CrewAI — roles + hierarchical manager-worker + the cap
from crewai import Agent, Crew, Process
crew = Crew(agents=[...], process=Process.hierarchical, max_iter=15)   # max_iter = your safety cap

# AutoGen — group chat, speaker selection, termination
from autogen import GroupChat, GroupChatManager
gc = GroupChat(agents=[...], max_round=12)            # max_round = the hard stop
manager = GroupChatManager(groupchat=gc, is_termination_msg=lambda m: "TERMINATE" in m["content"])

# LangGraph — shared State + edges + recursion limit (the stall/loop guard)
graph.invoke(state, config={"recursion_limit": 25})  # raises instead of looping forever

# OpenAI Swarm — agents + handoffs (the router/dynamic-handoff pattern)
def transfer_to_specialist(): return specialist_agent  # a tool that returns the next agent

War stories

  • The critic that never said yes. A "quality reviewer" agent was prompted to be exacting; it rejected every draft, the executor revised forever, and the bill ran until someone killed the job. Fix was one line — max_revisions — plus stall detection so it halts the moment the draft stops changing instead of paying out the whole cap.
  • The $400 "collaboration." A five-agent "team" re-read the entire growing transcript every turn. Quality was no better than one agent; cost was 8×. We deleted three agents, scoped the remaining two's context, and kept a single critic. Better and cheaper.
  • Best-of-7 that agreed on garbage. Majority vote over seven samples of the same model/prompt looked rock-solid in the dashboard and was confidently wrong on a whole class of inputs — every sample shared the same blind spot. Voting needs diverse inputs; we added a second model and an adversarial critic.
  • The unreproducible bug. A handoff order depended on dict iteration, so the system behaved differently every run and the intermittent loop was "impossible to reproduce." Pin the order (list + cursor), pin sampling, pin tie-breaks — then you can debug.
  • The pipeline that should've been one prompt. A "planner + executor" for a task one agent did in a single call. The plan step added latency and a failure point and improved nothing. Distinct roles weren't actually distinct.

Vocabulary (rapid-fire)

  • Blackboard — shared, authored, append-only state agents read/write instead of calling each other.
  • Role / policy — role is a label; policy (policy(view)->action) is the behaviour (a prompt+LLM, or an injected callable).
  • Planner / executor / critic / router — decompose / do / review / pick-next-speaker.
  • Critique-revise (reflection) — draft → critic accepts or returns notes → revise; cap it.
  • Scheduler — who acts next: round-robin (fair), priority (opinionated), dynamic handoff.
  • Consensus / self-consistency — majority vote over samples; weighted vote for expert agents.
  • Groupthink — shared bias across agents; voting amplifies confidence, not correctness.
  • Stall detection — halt when no new progress (no-op rewrites) over a window.
  • Termination guards — max rounds + stall detection + budget.

Beginner mistakes

  • Reaching for multi-agent when one agent with tools already wins — adding coordination, not capability.
  • Shipping a critique-revise loop without a cap (the classic infinite-loop incident).
  • Relying on a bare max_rounds and paying the full budget on a task that stalled early.
  • Letting schedule/tie-break order depend on set/dict iteration → non-reproducible, undebuggable.
  • Trusting majority vote over agents that share the same model/prompt/context (groupthink).
  • Forgetting that shared context is tokens — every agent, every turn — so cost scales with the conversation.
  • No authorship on shared state, so when the team produces garbage you can't tell which agent did it.

The one thing to take away

Before you add an agent, name which of the three reasons (distinct role / parallel / cross-check) justifies it — and before you ship it, point to the cap, the stall detector, and the budget that make it stop. If you can't, you don't have a system; you have a loop with a credit card.