The Supervisor Pattern: When One Agent Isn't Enough

I built a multi-agent system by giving five agents full access and letting them coordinate. Two of them edited the same file simultaneously. The merge was incoherent. The tests failed. Neither agent understood why.

That was the day I learned: multi-agent without a supervisor is just chaos with more compute.

One supervisor, scoped specialists

The pattern is hierarchical, not democratic. One supervisor agent owns the main loop. It decomposes the task, dispatches specialists, validates their output, and merges results. Specialists never talk to each other — all coordination flows through the supervisor.

supervisor_run(task):
  plan = dispatch(planner, { objective: "break task into subtasks" })

  for subtask in plan:
    // Each specialist gets:
    //   - only the tools its role needs
    //   - only the context for its subtask
    //   - its own bounded execution loop
    result = dispatch(subtask.role, subtask.context,
                      tools=subtask.allowed_tools,
                      max_iterations=subtask.timeout)

    if not result.success:
      // retry once, then escalate to human
      retry = dispatch(subtask.role, context + result.failures)
      if not retry.success:
        ask_user("Subtask failed twice. Skip, retry, or cancel?")

    results.merge(result)

  // Final review pass
  dispatch(reviewer, { diffs: results.all_diffs })

Tool restrictions per role

The most important constraint: specialists don't get full tool access. A planner gets read-only tools. A tester gets test and read tools. A reviewer gets read and diff tools. An implementer gets read and write tools but no git push.

This isn't about trust — it's about blast radius. When a reviewer can't accidentally edit files, a whole class of bugs disappears.

When to add multi-agent (and when not to)

Start with a single agent. Get it working reliably. Add a supervisor only when you hit a concrete wall: the task requires different expertise for different phases, or independent subtasks that could run in parallel, or you need isolation between concerns.

Most tasks don't need multi-agent. A single loop with the right tools handles 90% of coding tasks. The supervisor pattern is for the other 10% — and it's significantly harder to debug.

The anti-pattern: agent swarms

Spawning many agents with full access and no coordinator is the most expensive way to produce broken code. They step on each other's changes, duplicate work, and create merge conflicts that no individual agent understands.

If you need multiple agents, route everything through one supervisor. If you don't need multiple agents, don't add them for the architectural thrill.

The takeaway

Multi-agent is a coordination pattern, not a capability pattern. The supervisor makes it work by owning all routing decisions and restricting what each specialist can do. Without that control, more agents means more problems.

Next: Sandboxing Agents: Security as Architecture