Skip to content
AI360XpertBeta

Sub-Agents and Handoffs

One receptionist agent hears your request, then hands you and your notes to the right specialist, so you never repeat yourself.

A triage agent scores the request and hands history plus a task brief to the refund specialist
A triage agent scores the request and hands history plus a task brief to the refund specialist

Why Does This Exist?

You build one support agent and hand it everything: the refund policy, the sales catalog, the troubleshooting guide, plus a dozen tools. It works in the demo. Then real requests arrive and the cracks show. The prompt grows to thousands of tokens, the model reaches for the wrong tool, and a refund question gets a sales answer. Every new skill you add makes every old skill a little worse.

Splitting the job fixes the bloat but creates a new problem: who decides which specialist talks to the user? That is what a handoff does. One small triage agent hears the request first, picks the right sub-agent, and moves the conversation there with the notes attached.

This page covers that split: how the router decides, what travels in the handoff, and what breaks when you get it wrong. The team patterns around it live in multi-agent systems. What a single agent loop looks like before you split it is in AI agent architecture. The call mechanism itself is ordinary tool calling: the router calls something like transfer_to_refunds(), and your code treats that call as a change of speaker rather than an API request.

Think of It Like This

A clinic reception desk

You walk into a clinic and say your shoes rubbed your heel raw. You do not pick your own doctor. The receptionist listens for one minute, writes your name, your symptoms, and your chart number on a slip, and walks you to the wound-care nurse. The nurse reads the slip and starts treating you. You never repeat your story.

The receptionist is the triage agent. The slip of paper is the handoff package. Each department is a sub-agent with its own tools and instructions.

Where it stops: clinic staff share a building, training, and a records system. Your agents share nothing except what your code passes. If the slip is blank, the specialist starts from zero, and no hallway conversation saves you.

How It Actually Works

Three pieces do the work: a router that scores, an orchestrator that switches speakers, and a package that carries state. Keep them separate in your head, because each fails in its own way.

The triage decision

Let SS be the conversation state, meaning the messages so far plus any facts you have pulled out. Let AA be the set of specialists, for example A={refund,sales,support}A = \{\text{refund}, \text{sales}, \text{support}\}. The router scores each one: ri(S)r_i(S) is the routing score of specialist ii given state SS, a number between 0 and 1, with the scores summing to 1. The chosen specialist hh is simply the highest scorer, written h=arg⁡max⁡iri(S)h = \arg\max_i r_i(S), which reads "pick the ii with the largest score."

Your code routes only when the win is clear. Let τ\tau be the confidence threshold, the minimum top score you accept, and let δ\delta be the margin threshold, the minimum gap between first and second place. Route when the top score beats τ\tau and beats the runner-up by more than δ\delta. Otherwise ask a clarifying question or keep the triage agent talking. Two numbers, one rule, far fewer misroutes.

The handoff package

The handoff package HH is what the new speaker receives. It has three parts: a short brief (what the user wants, in one or two sentences), the facts (order number, item, dates, anything already said), and a slice of recent history (the last few messages, verbatim). The specialist starts a fresh loop with its own system prompt, then HH pasted after it. Nothing else carries over. Tool permissions, private reasoning, and half finished tool calls stay behind unless you copy them in.

This is the trade-off you are buying. Short prompts per specialist mean sharper answers and fewer wrong tool calls, and you pay for it with extra machinery: more prompts to maintain, more model calls per conversation, and a router that can be wrong. Do not use this pattern for two overlapping intents or a single well understood task. One prompt with clear instructions is cheaper and easier to test. Reach for handoffs when you have three or more distinct jobs, each with its own tools and policies, and mixing them in one prompt has already caused mistakes. The standing assumption is that intents are separable and the package fits the next window. When requests genuinely blend, say a refund that turns into a new purchase, the router guesses, and the guess shows up as a bounce between specialists. Passing a slice instead of the full log is the usual fix for the size side, and the full treatment of that squeeze is in context compaction.

Worked example: a refund request

Suppose the user writes: "These shoes do not fit, I want my money back." The triage agent scores the state SS:

  • rrefund(S)=0.82r_{\text{refund}}(S) = 0.82
  • rsales(S)=0.11r_{\text{sales}}(S) = 0.11
  • rsupport(S)=0.07r_{\text{support}}(S) = 0.07

Check the arithmetic yourself: 0.82+0.11+0.07=1.000.82 + 0.11 + 0.07 = 1.00, so the scores are a proper split. The margin over the runner-up is 0.82−0.11=0.710.82 - 0.11 = 0.71. With τ=0.60\tau = 0.60 and δ=0.20\delta = 0.20, the top score clears both bars (0.82>0.600.82 > 0.60 and 0.71>0.200.71 > 0.20), so the orchestrator stops the triage loop and starts the refund specialist. These are the same numbers drawn in the diagram above.

The package HH carries 4 facts (order 88412, shoes size 9, reason too small, wants refund) plus the last 4 of 6 messages, counted here as 380 tokens. The refund specialist has its own 520 token system prompt. Its first input is 520+380=900520 + 380 = 900 tokens. Short, complete, and the user never repeats the order number. If the refund later needs a sales answer, the specialist calls back with a return handoff, and the same rules apply in reverse. When that ping-pong repeats, treat it as a bug, not a conversation: the failure catalog for these loops is in agent failure modes.

Code

This snippet is the whole pattern with the model calls removed, so you can read the switching logic on its own. Type hints included, no dependencies.

from dataclasses import dataclass

@dataclassclass Handoff:    target: str    brief: str    input_tokens: int

def route(message: str) -> Handoff:    text = message.lower()    refund_hits = sum(w in text for w in ["refund", "return", "money back"])    sales_hits = sum(w in text for w in ["buy", "price", "discount"])    if refund_hits > sales_hits:        return Handoff("refund", "return shoes size 9, order 88412", 900)    return Handoff("sales", "general enquiry", 640)

h = route("These shoes do not fit, I want my money back")print(h.target)        # -> refundprint(h.input_tokens)  # -> 900print(h.brief)         # -> return shoes size 9, order 88412

The message contains one refund phrase ("money back") and zero sales phrases, so refund_hits is 1, sales_hits is 0, and the router picks the refund branch with the 900 token input from the worked example. In production the scores come from the model and the token count from your tokenizer; the switching line stays the same.

Watch Out For

The specialist asks for facts the user already gave

Symptom: the user told triage their order number, the handoff fires, and the refund agent opens with "What is your order number?" Trust drops at once.

The cause is a package with intent but no facts. Your orchestrator passed the last messages or nothing at all, and the specialist's prompt never extracts the details into a brief. Fix it by asserting the required fields before you route: order id, item, and reason present, else triage asks first. Then have the specialist read one fact back ("For order 88412, the size 9s, correct?") so a silent drop shows up in one turn.

Two specialists bounce the user back and forth

Symptom: refund hands to sales, sales hands back to refund, the same question appears twice, and the token bill climbs while nothing resolves.

The cause is overlapping territory with no owner. Each specialist sees a reason the other should handle it. Fix it with a single-owner rule: at most one handoff per turn, and a return trip needs new evidence such as a fetched order record. Log every handoff with its scores, and review any conversation with two or more handoffs that week.

The Quick Version

  • A handoff moves a live conversation from a triage agent to the specialist sub-agent that owns the task.
  • The router scores each specialist and switches speakers only when the top score clears a threshold with a clear margin.
  • The handoff package carries a brief, the extracted facts, and a slice of recent history, pasted after the specialist's own prompt.
  • Splitting prompts sharpens each specialist at the cost of more machinery, more calls, and a router that can misfire.
  • A dropped package shows up as repeated questions, and overlapping specialists show up as bounces, so log every handoff with its scores.