Four designs that come up repeatedly, each with the configuration that builds it. Every hop here is a handoff — agent to agent. Handing the caller to a person is a transfer, and the two are never interchangeable.

​
1. Front desk to specialists

The default shape. One triage agent answers, works out what the caller needs and routes; the specialists do the work. The front desk carries one handoff per desk and a prompt that says what it does not answer:
Three descriptions that do not overlap is most of the work. If billing says “payments” and renewals says “plan changes”, a caller asking to change their card and their plan in one sentence is a coin flip — put the card in billing’s description explicitly, as above. Each specialist’s prompt should say what its desk does, its own rules and its own tool use, and should not repeat the routing policy. It has already been chosen; a specialist that re-litigates which desk the caller wants sends them round again. Two things it should carry instead:
  • What to do with something outside its remit — which is pattern 2 below.
  • A line telling it not to re-introduce the company. The caller has heard the greeting once, and the target speaks its own greeting on arrival. Either give the specialist a short greeting that assumes the handover (“Billing here — I can see your account”), or give it none at all and let it open by answering.

​
2. Returning to the front desk

A specialist that discovers it has the wrong caller hands back. There is nothing special about the return edge — it is an ordinary handoffs entry on the specialist, pointing at the front desk:
context: "none" with a small recent_turns is what makes the return cheap. The front desk’s job is to route, and routing needs the last thing the caller said, not the billing detour it just sat through. Under transcript the front desk would re-read the whole specialist conversation on every turn — and then route on it, which is worse than useless: it now knows a great deal about a question that has been answered. Two things to know about return edges:
  • The specialist’s edge counts as an edge, so the expressive and media rules apply to it in both directions.
  • Loops are capped at 25 handoffs per call. If a caller can bounce between two desks, the descriptions overlap. Fix the descriptions rather than relying on the cap, which the caller hears as “I’m sorry, I can’t pass you to another assistant again on this call.”

​
3. Conditional routing on a lookup

Tier, entitlement and ownership are facts about the account, not judgements about what the caller said. Look them up and route on the answer, in a handoff operation inside a tool. The agent carries both mechanisms at once:
route_by_account is the tool built on conditional handoffs: it looks the account up and, if it is enterprise, hands to the account manager. Billing stays on handoffs, because which desk a billing question belongs to is exactly the judgement the model is good at. The order matters in the prompt. A tool that may end the turn by handing over should be called before the agent starts answering, not after.

​
4. A cast assembled per call

Reach for agent_team when the cast genuinely differs per request: a marketplace where the specialist is the seller’s own generated agent, an outbound campaign where each region’s closer is picked from your own data, a demo that composes an agent from a form.
members[0] answers. The opener reaches the closer through a handoffs entry named Closer with no agent_id, which resolves in this call’s roster. If nothing reaches a member, the response’s warnings says so. If the same two agents run on every call, this is the wrong mechanism — store the edge on the opener and dial one agent_id.

​
The constraints that shape a team

Expressive delivery must match across every outgoing edge. A target of an agent with tts.expressive on must use the same provider, the same model and expressive: true, or publish refuses it — the target inherits a transcript full of tags and a voice that cannot speak them reads them out. Handing off into an expressive agent is fine. See expressive delivery. Keep voice and language consistent unless you mean the change. Nothing enforces this beyond the expressive rule, so a team can hand a caller from one voice to a completely different one mid-call — which sounds like being passed to a colleague, and is fine if that is what you want and jarring if it is not. If the voices do change, have the target’s greeting say who it is. If they do not, give every member the same tts block. The same goes for language: a caller who was speaking Hindi to the front desk should not be answered in English by billing. Every hop costs something. At the boundary the platform loads the target’s published definition, its pinned tools, its knowledge and its hooks, and builds its models — that is the pause the message exists to cover. Under context: "summary" there is a second pause first, while the source agent writes 60–100 tokens. After that, the target pays for whatever crossed on every turn it takes, on your own provider key. Two hops on a short call are unnoticeable; a transcript hop late in a long call is the most expensive thing on it. See context policies. Recording cannot start part-way through a call. If the agent that answers has recording off and a target has it on, nothing is recorded — publish warns about the edge, and the call records a recording.unavailable event when it actually bites. Recording switching off mid-call always works, which is what makes “support → payments → support” a usable shape. See recording.

​
Reading a multi-agent call afterwards

Do not read the session row as “who handled the call”. One call is one session, and the session names the agent that picked up; per-turn attribution is on the items. See conversations and calls.

​
Next

Multi-agent triage

The front desk pattern built end to end, with a number answering.

Context policies

Choosing what each hop carries.

Conversations

Sessions, items and finding one person’s history.