Multi-Agent Systems

What a multi-agent system is

The reason to split is specialisation: a worker with four tools and a short prompt decides better than one with thirty tools and a two thousand word prompt. The reason not to split is that every boundary costs context, tokens, latency and the ability to say which component was wrong.

Terms used on this page

Supervisor

The agent that plans and routes but does no domain work. It decomposes the request, dispatches to workers, validates their results and synthesises the answer.

Worker

A narrow agent with one job, a small tool list and its own permission ceiling. It answers exactly the objective it was handed and reports what it could not settle.

Handoff envelope

The typed message passed from one agent to another. It carries the objective, the resolved inputs, the shared facts, the budget, the permission ceiling and the conditions for being finished.

Hop

One handoff between agents. Capping hops per run is the standard defence against two agents passing a task back and forth until the budget is gone.

If you do not yet run a single agent in production, start there. The patterns on AI agent development are prerequisites, and a team that has not shipped one agent will not debug five.

Who it is for, and who should stay with one agent

Multi-agent systems suit work that crosses real boundaries: different tools, different permissions, different data sensitivity, different owners. They do not suit work that is merely large. A long job with one tool set is a single agent with a bigger step budget.

The Handoff Tax, and how to price a split

Every boundary between agents has a price, and it is payable on every run forever. Naming the six line items makes the split decision arithmetic rather than taste.

What we actually build

The system is a registry, an envelope, a set of narrow workers, a supervisor and a trace that spans all of them. The workers are the easy part.

The worker registry

A single file listing every worker: its name, its one sentence job, its tool list, its permission ceiling and the shape of what it returns. The supervisor may dispatch only to a name in this registry, enforced in code rather than requested in the prompt. That prevents a supervisor inventing a plausible specialist and then hallucinating its reply.

The envelope and its validator

One typed message format for every handoff, validated on the way out and on the way in. A dispatch that fails validation never reaches a worker, and a result that fails validation never reaches the synthesis step. This is where most reliability comes from, and it is ordinary schema work rather than anything to do with models.

The fact ledger

A small store, scoped to one run, holding values that more than one worker needs: the customer tier, the applicable policy version, the currency, the cut-off date. Each entry records which tool call produced it. Workers read from it and are forbidden to re-derive its entries. This one component removes most self-contradicting output.

1. The supervisor, with dispatch, ask and finish, and no domain tools at all.
2. Narrow workers, each with a small tool list and its own permission ceiling.
3. The registry, the envelope schema and validators on both directions of every hop.
4. The run-scoped fact ledger with provenance on every entry.
5. Hop counters, per-worker budgets and a duplicate-objective detector.
6. A trace joined by run_id across every agent, queryable as one story rather than five logs.

How it works technically

A request enters the supervisor. It resolves the shared facts it can, writes a plan, and dispatches the first objective in a validated envelope. Each worker runs its own agent loop inside its budget, returns a typed result with evidence and an unresolved list, and the supervisor decides whether to accept, re-dispatch or escalate.

1. The supervisor resolves shared facts first, before any dispatch, so no two workers can answer the same underlying question differently.
2. It writes a plan naming the workers it intends to use and why. The plan is stored, which makes the routing decision reviewable later.
3. Each dispatch is an envelope validated against the schema. An invalid envelope is a supervisor bug and never reaches a worker.
4. The worker runs its own loop with its own tools, budget and permission ceiling. It cannot see the other workers and cannot dispatch.
5. The result is validated: status, evidence for every assertion, and an explicit unresolved list. Missing evidence is a rejection, not a warning.
6. The supervisor accepts, re-dispatches with a corrected objective, or escalates. Hop counts and duplicate objectives are checked at this point.
7. Synthesis runs over accepted results only, and may not introduce a claim that no worker returned.

The envelope schema below is the piece worth stealing. Almost every multi-agent failure we have debugged traces back to an untyped handoff: a worker that received a summary instead of the document, a result accepted with no evidence, or two agents passing the same task back and forth because nothing counted hops.

{
  "$id": "handoff_envelope.schema.json",
  "type": "object",
  "additionalProperties": false,
  "required": ["run_id", "hop", "from", "to", "objective", "inputs", "authority", "budget", "done_when"],
  "properties": {
    "run_id":    {"type": "string",  "description": "Identical for every hop in one request. This is how the trace is reassembled later."},
    "hop":       {"type": "integer", "description": "Increments on every handoff. Reject anything above max_hops. This is what kills ping-pong."},
    "from":      {"type": "string"},
    "to":        {"type": "string",  "description": "A worker name from the registry. The supervisor may not invent one."},
    "objective": {"type": "string",  "description": "One imperative sentence. If it needs two, it is two handoffs."},
    "inputs":    {"type": "object",  "description": "Resolved values only. Never a pointer the worker has to fetch, never a summary of a document it needs in full."},
    "facts": {
      "type": "array",
      "description": "Shared values resolved ONCE upstream. A worker must use these and must not re-derive them.",
      "items": {"type": "object", "required": ["key", "value", "source_tool_call_id"]}
    },
    "authority": {"type": "string", "enum": ["R0", "R1", "R2", "R3", "R4"],
                  "description": "Highest reversibility class this worker may act at on this hop. Enforced in code, never by the prompt."},
    "budget":    {"type": "object", "properties": {"max_tool_calls": {"type": "integer"},
                                                   "max_tokens": {"type": "integer"},
                                                   "deadline_ms": {"type": "integer"}}},
    "done_when": {"type": "array", "items": {"type": "string"},
                  "description": "Machine checkable conditions. The supervisor validates these before accepting a result."},
    "return": {
      "type": "object",
      "required": ["status", "result", "evidence", "unresolved"],
      "properties": {
        "status":     {"enum": ["done", "partial", "refused", "failed"]},
        "result":     {},
        "evidence":   {"type": "array", "items": {"type": "string"},
                       "description": "tool_call_ids supporting each asserted value. An assertion with no evidence is rejected."},
        "unresolved": {"type": "array", "items": {"type": "string"},
                       "description": "What this worker could not settle. An empty array is a claim, not a default."},
        "confidence": {"type": "number"}
      }
    }
  }
}

Three fields do the heavy lifting. The facts array kills consistency drift, because a worker that must use a supplied value cannot invent a different one. The authority field carries the permission ceiling per hop, so a research worker cannot be talked into sending an email. And unresolved makes uncertainty a first class output rather than something a worker quietly omits.

ROLE
You are the supervisor. You do not do the work. You decompose it, dispatch it,
verify what comes back and synthesise the answer. Your only tools are
dispatch(), ask_user() and finish().

DISPATCH RULES
Dispatch only to a worker in the registry below. Never invent a worker name.
One objective per dispatch, written as a single imperative sentence.
Resolve shared facts yourself before dispatching and put them in envelope.facts.
A worker must never look up a fact another worker has already resolved.
Set envelope.authority to the lowest class that lets the worker finish.

ACCEPTING A RESULT
Reject status="done" when any done_when condition is unmet.
Reject any asserted value whose evidence array is empty.
A worker returning unresolved items is doing its job. Do not paper over them.

STOPPING
Maximum 3 hops to any one worker and 12 dispatches per run.
If two workers disagree on a fact, do not average them and do not pick the more
confident one. Re-dispatch to the worker that owns that fact, or escalate.
If the same objective has been dispatched twice, escalate with reason="loop".

SYNTHESIS
Your final answer may contain only claims present in a worker result with
evidence attached. You may not add knowledge of your own, and you may not
smooth over a contradiction between two workers.

Topologies, and where each one breaks

The build process, stage by stage

Six to twelve weeks, and it starts by trying not to build it. The first stage exists to give the split decision a chance to fail cheaply.

What you get at handover

Everything from a single agent handover, plus the artefacts that make a distributed system debuggable by somebody who was not there when it was built.

The trace viewer matters more here than anywhere else. Five agents produce five sets of logs, and reading them side by side to reconstruct one decision is a job nobody does twice. If a run cannot be read as one story, the system is undebuggable and gets switched off the first time it is blamed for something.

Where these projects go wrong

Single agent failures are mostly about tools and evaluation. Multi-agent failures are almost entirely about boundaries, and they are harder to see because every individual component looks fine.

The split followed the org chart

A sales agent, a support agent and a finance agent, because that is how the company is arranged. They share most of their tools, they need most of the same facts, and the supervisor spends its budget shuttling context between them. Six months later somebody merges two of them back and performance improves.

The supervisor summarised instead of passing evidence

It reads a document, writes a three line summary, and dispatches that. The worker then answers correctly from an input that lost the exception clause on page four. This is the single most common cause of confident wrong answers in a multi-agent system, and the fix is structural: envelopes carry resolved values and references to full sources, never a model's compression of them.

Nothing counted hops

Two workers each decide the task belongs to the other. Without a hop counter and a duplicate-objective check, they will pass it back and forth until a budget runs out, and the cost lands on a bill three weeks later. A hop cap is four lines of code and it is not optional.

Shared facts were re-derived per worker

Two workers independently look up which pricing policy applies, at slightly different moments or through slightly different tools, and get different answers. The supervisor synthesises both. The output contradicts itself inside one paragraph and looks, to a reader, like carelessness rather than an architecture defect. There is more on this pattern in how agents fail.

Quality was measured at the system level only

One aggregate accuracy figure across the whole run hides a single failing worker behind four competent ones, especially when that worker handles the least frequent case. Sample per worker, and weight by how much damage each worker can do rather than by how often it runs. This is what agent observability exists to support.

What it costs to run once live

A multi-agent system costs several times what one agent costs for the same request, and the multiple is mostly briefing overhead rather than useful work. Look at the multiple rather than the absolute figure, because the multiple survives price changes.

Two things the arithmetic understates. Supervisor synthesis runs over a context holding every worker result, so its calls are the largest in the system and grow with the number of workers. And a rejected result is paid for twice, once when the worker produced it and again when the corrected objective is re-dispatched, which is why validation strictness has a direct price.

How to tell whether you need more than one agent

The test is not how complicated the work feels. It is whether the work crosses a boundary that a single agent cannot hold without contradicting itself.

Two or more rows on the right, one of which is tools or permissions, means the split is probably real. Rows on the right that are all about organisation and none about tools means you have a staffing question rather than an architecture one, and the guide on when to use multiple agents works through the marginal cases.

How to start

Start by trying to avoid it. The cheapest multi-agent project is the one a two week measurement talks you out of.

1. A scoping call45 minutes

   You describe the work and where the current approach strains. We are looking for boundaries: tools that do not overlap, permissions that must not be shared, data one part of the job should never see.

2. The split test1 to 2 weeks

   We measure the existing agent, or build a single agent first, and locate where it actually loses. Roughly as often as not this stage ends with a recommendation not to split, which is a cheaper outcome than discovering it in week nine.

3. Contracts before agents1 week

   Registry, envelope schema, fact ledger, permission ceilings and hop caps, agreed and written down before any worker exists.

4. Build, attack, shadow, cut over6 to 12 weeks

   Workers evaluated in isolation, supervisor built last and attacked deliberately, then a shadow run at full topology and a cutover on a slice with per-worker sampling.

5. The boundary reviewNinety days after cutover

   We look at the dispatch plans and ask whether each boundary is still earning its tax. Merging two workers back together is a legitimate result and we have recommended it more than once.