the most undervalued primitive
a handoff is how one agent passes control to another. it's the pattern that makes multi-agent systems possible and, if done badly, the pattern that makes them unreliable. most "the agent got confused" bugs in production are bad handoffs in disguise — too much context leaking through, not enough context handed over, or transfers that happen silently without the next agent understanding why.
the rule, always: a handoff is explicit and typed. no shared blackboards. no "just read the history." if the receiving agent needs to know something, the handing-off agent puts it in the payload.
triage hands off — runnable
four things this gets right on purpose:
- it's a value, not a side effect.
triage returns a
Handoff; it doesn't call the billing agent directly. the orchestrator routes. this means every handoff is loggable, testable, and replayable. - the reason is mandatory. "why did triage hand this to billing?" is the most useful question a trace can answer. forcing a reason string turns runtime confusion into a one-line audit.
- the payload is narrow.
billing gets exactly what it needs (
userId,invoiceId) — not the whole chat. no distraction, no leaked context. - a handoff is not a return. triage is done. billing starts a new turn from the payload. the old conversation doesn't follow unless it's summarised in the payload. this is the single biggest mental-model shift.
payloads: the contract between agents
the payload is everything. too much and the receiving agent gets distracted by irrelevant history and repeats work. too little and it asks the user questions triage already asked. the right amount is surprisingly small: ids, the intent, and a 1–2 sentence summary of anything that matters. treat the payload like an api contract, because that's what it is.
when it breaks
- the full-history payload. passing every prior turn "just in case" turns the next agent into a re-triager. it re-reads, re-classifies, sometimes re-decides — and you pay tokens for the privilege.
- circular handoffs. billing hands back to triage, triage hands to support, support hands to billing. without a turn budget or explicit "don't hand back to an agent that already saw this", you get a loop that eats budget quietly.
- handoff by prompt instruction. "if the question is about billing, please transfer to the billing team" in the system prompt is not a handoff. it's a suggestion the model may or may not follow. make it a return value; force the route through code.
- the user doesn't know it happened. a silent handoff followed by a different voice, tone, or refusal breaks trust. either keep the ux continuous (the persona change is invisible) or announce the transfer — don't land somewhere between.
next: loops — the control flow inside a single agent turn. when to iterate, when to stop, and how to avoid the runaway budget.