Swarm / handoff

Read these first

• Orchestrator–worker

What you will know

• Implement peer-to-peer handoff with no supervisor

  The transfer needs explicit ownership, state, provenance, and termination data or the receiving agent must guess what remains to be done.

• Measure what is lost at each handoff

  Context, tool results, constraints, confidence, and stop conditions can disappear even when the next agent appears to have enough information.

• Debug a run where control went somewhere unexpected

  A useful investigation correlates agent messages, routing decisions, state mutations, and timestamps to expose cycles and accidental delegation.

• Bound a swarm so it cannot run away

  Per-agent limits are insufficient; enforce global hop, token, time, spend, and duplicate-work budgets across the entire run.

• Compare a peer handoff against a supervisor on the same workload and budget

  Peer routing may remove a central bottleneck, but often adds hops, duplicated work, weaker observability, and harder recovery.

Chapters

1. 1

   Nobody holds the goal after a peer transfer

   In the orchestrator design, one component receives every result and decides what happens next. When triage calls transfer_to_refunds() and stops running, refunds owns the conversation and can pass it onward, and no component holds the goal, can stop the run, or can restart it. The transfer is itself an inference call, made by an agent carrying a full conversation, so it is rarely the cheaper hop it is sold as.

   Read chapter
2. 2

   A transcript is evidence; the receiver needs a contract

   Refunds keeps re-asking for the order number that triage already collected and confirmed, and the transcript was right there in the payload. Handing over prose asks the receiving agent to re-derive a contract from it. Define the transfer payload instead: what has been established and by whom, what remains to be done, who owns the task now, the run's remaining budget, and what would end it.

   Read chapter
3. 3

   Who may hand to whom is a decision, not a default

   A swarm in which every agent can transfer to every other is a choice somebody made by not making one. The reachable graph is a design variable: which peers each agent's transfer tool even exposes, whether control may return to an agent that has already held the conversation, and what the caller is shown about a destination before committing to it. Work through the proposal to forbid transferring to any agent that has already seen the conversation, and you find it forbids legitimate returns — refunds back to triage back to refunds is an ordinary path — while leaving cycles among not-yet-visited agents unbounded, which makes it a routing restriction standing in for the run-level budget that is actually missing.

   Read chapter
4. 4

   Constraints travel worse than goals across a handoff

   A customer asks for a refund and asks not to be emailed about it. Triage hands to refunds, refunds hands to notifications, the refund is correct and the email goes out, and every agent behaved sensibly given what it received. Goals get forwarded because they are the task; constraints get dropped because no field held them, and passing the whole transcript instead just restores the judgement call that already failed. Then turn the loss into a measurement rather than an anecdote: set each receiver's payload against what the sender actually held — established context, tool results, constraints, confidence, stop conditions — and score the gap field by field across a run set, so a dropped constraint is a number you watch instead of a customer complaint.

   Read chapter
5. 5

   One run-scoped trace turns routing into something investigable

   The billing agent answered a shipping question and nobody can reconstruct how control arrived there, because per-agent logs record prompts, outputs and tool calls but never the decision to transfer. Record every routing decision with the reason given for it, the state before and after each handoff, and a timestamp, all correlated under one run ID. Without that, tightening routing prompts is guesswork about which agent went wrong.

   Read chapter
6. 6

   Per-agent caps bound the hop, never the number of hops

   A support run cost $38 over nine minutes with no agent exceeding its 10-call, 25k-token cap and no error logged, and the run-scoped trace of the previous chapter is what shows why: control simply circulated, and a per-agent log has no record of a transfer to reveal it. Halving the caps makes the loop take more, cheaper laps. Attach hops, tokens, spend and wall-clock to the run itself, decremented at every transfer, and carry the termination conditions in the payload so whoever holds an unfinishable run can return a partial answer with its gaps named.

   Read chapter
7. 7

   Peer routing removes the bottleneck and pays in hops

   Held to the same workload and the same budget, a swarm buys the loss of a central component and usually pays for it in extra hops, duplicated work, weaker observability and a harder recovery story. This chapter sets that comparison up honestly, and asks what evidence a director should want before mandating a supervisor, including the case where you say no even though the swarm is losing today.

   Read chapter