Handoffs reference

​

What it gives you

​

How it works

1. The model calls the handoff tool. Its handler calls hand_off.
2. The announce line is said, and the handoff waits for it to play.
3. With history="summary", the summary request runs while the line plays.
4. The next agent gets its history, its prompt and its tools, and its own model and voice when it has them.
5. The next agent replies first. That reply offers none of its handoff tools.

• LiveKit says it with allow_interruptions=False, so the caller cannot cut it off.
• Pipecat has no such flag for one line. It says the line while the handoff call still runs, so user_mute_strategies(protect=["tool_calls"]) keeps the caller from cutting it. Without that strategy, a cut line counts as played. Pipecat waits at most 30 seconds for the line.

​

HandoffContext

​

UnmuteAgent.hand_off

​

UnmuteFlows.hand_off

• The spec lists a handoff that is not one of native_tools.
• A task names a model, or transfers to an agent then_targets lacks.
• The spec has a model without a ModelCallLLMService.
• tts is not one of the call’s voices.
• opens_with names a tool the spec lacks, or the model is a realtime one.

​

History rules

• The announce line is the last thing the next agent hears, in messages, full and last_n.
• A step’s finish calls and the step-start cue never cross. The step-start cue is the short line (The call continues.) that opens a step when the caller has said nothing in it yet. The next agent would read them as its own work, or as the caller.
• On a realtime model, only full works. The model keeps the whole conversation on its server. Pass HandoffContext(history="full"). Any other value is refused. See Realtime models.

​

History helpers

from unmute_core.handoff import call_name, newest_caller

newest_caller(chat, skip_cue=True)  # the caller's newest message, or None
call_name(call)  # the function name of one tool_calls entry, or None

1. newest_caller(messages, skip_cue=) returns the caller’s newest message. It returns the message itself, not a copy.
2. With skip_cue=True, it passes over the step-start cue, which the caller never said. It returns the turn before the cue.
3. call_name(call) reads the name from one entry of a message’s tool_calls.

​

The summary

HandoffContext(history="summary", summarizer=my_model_call)

1. The library sends one model request at the summary site, with no tools. It holds a fixed prompt and the conversation as role: text lines. Prompts, tool calls and tool results are left out.
2. summarizer is any ModelCall, like a LiveKit plugin in LiveKitModel. Without one, the agent spec’s summarizer answers. Without that, the model of the agent that hands off answers, by the path the finish check uses.
3. On Pipecat, the agent’s own model can answer only through a ModelCallLLMService, an OpenAI-compatible service or a GoogleLLMService. Give any other service a summarizer.
4. A summary that fails, comes back empty, or takes longer than 8 seconds is dropped. The next agent then hears messages. The call goes on.
5. The request is traced as an llm span in the open turn, with site summary.
6. On the SLNG Context Router, the request goes out under the agent’s own id, with prompt site task:summary. The router accepts only task:<name> as a prompt site, so no task or group may be named summary. See SLNG.

​

Model and voice on each framework

1. The announce line plays in the old voice, and a summary is written by the old model.
2. Then the new model and voice take over. The new agent’s first reply, its steps, finish checks and summaries all use them.
3. An agent whose spec has no model runs on the call’s first model. That is the session’s LLM on LiveKit, and the model call the ModelCallLLMService was built with on Pipecat. The same holds for the voice.
4. The llm spans name the model each request went to. The tts spans name the voice.

1. The spec’s model takes a LiveKit plugin as LiveKitModel(plugin), or any other ModelCall, like the SLNG Context Router. Without it, the agent runs on the session’s LLM.
   • A ModelCall is retried as the session retries its own LLM. It uses the session’s conn_options. It retries only before the first event, and only when the call does not retry itself (retries_itself).
   • When the session closes, the agent closes its ModelCalls, like the router’s HTTP client. A LiveKit LLM plugin stays open. LiveKit owns it.
2. A plugin answers as the session’s LLM does. The library fills the prompt, and the plugin’s chunks pass through unchanged.
3. UnmuteAgent(tts=...) is the agent’s voice. Without it, the agent speaks with the session’s TTS.
4. The agent’s steps run on its model and speak with its voice. A task’s own model still wins for its steps.
5. The spec’s summarizer and task_models take a plugin the same way, as LiveKitModel(plugin).
6. LiveKitModel(plugin) is the plugin as a ModelCall. It also fits HandoffContext(summarizer=LiveKitModel(openai.LLM(model="gpt-5.6-luna"))) and a FallbackModelCall. A tool call’s provider data, like a Gemini thought signature, comes back as ToolCall.extra, and the plugin sends it back when the call is replayed.

1. The spec’s model needs a ModelCallLLMService. The service swaps the model call it sends through. A native Pipecat service runs one model, and a spec with a model is refused there. For an agent on its own native model, give its spec model=OpenAIModelCall("gpt-5.6-terra"). See OpenAIModelCall. The service closes each model call it was given when the pipeline ends.
2. A spec with no model goes back to the model call the service was built with. A handoff back to the first agent passes its spec, with no model.
3. hand_off(tts=...) is one of the services of the VoiceSwitcher, the voice that speaks next. tts=None goes back to the switcher’s first service.
4. Two voices of one provider are two instances of its service. Each opens its own connection as the pipeline starts.
5. VoiceSwitcher is Pipecat’s ServiceSwitcher with one fix. A plain one lets each frame out once, so Pipecat’s flush probe is lost on its way back, and every handoff and task waits out the flush timeout. UnmuteFlows(tts=...) refuses a plain one.

​

The first reply after a handoff

• The first reply after a handoff.
• A greeting the model words, which answers no caller turn.
• The opening reply of a task step that offers handoffs.

billing = AgentSpec(BILLING_PROMPT, name="billing", handoffs=("to_front_desk",))
await self.hand_off(Billing(billing, state=self.state, native_tools=[...]))

billing = AgentSpec(BILLING_PROMPT, name="billing", handoffs=("to_front_desk",))
await flows.hand_off(params, billing, native_tools=[...])

1. The spec’s handoffs names the agent’s handoff tools. Neither framework can tell a handoff tool from any other. On LiveKit they are native_tools or @function_tool methods.
2. The first reply after the agent takes the call offers every other tool. A tool it calls is answered with the handoffs still left out.
3. The first request after the caller speaks offers them again.
4. A realtime model keeps every tool.
5. For a greeting, give the first agent’s spec its handoffs too. It is the same AgentSpec(handoffs=...) on both frameworks. A greeting you write yourself makes no model request, so it needs none of this.

​

Step handoff rules

1. The step offers to_notes after its own tools, with the same name and description as the main agent’s. Its opening reply leaves to_notes out. It comes back on the first request after the caller speaks in the step.
2. The handoff tool must be one of the agent’s own tools: a native_tools entry, or a LiveKit @function_tool method. The agent refuses a task that names any other tool.
3. When the step’s model calls it, the step ends with task.handed_off. Its task or group ends with it, and nothing is saved.
4. The next agent hears the step’s own chat, shaped by the handoff’s context.
5. A handoff in the same reply as another call of the step is refused, and asks for no reply. The other call runs. A handoff in a later reply of the same turn, after the step’s own tool returned, is not refused.
6. The step ends only once the next agent is ready. A handoff tool that raises, or returns no agent, leaves the step running.

​

Group transfer rules

TaskGroupSpec(
    name="take_payment",
    when="The caller is ready to pay.",
    steps=("confirm_amount", "take_card"),
    context_scope="shared",
    then="transfer",
    then_target="billing",
)

billing = AgentSpec(BILLING_PROMPT, name="billing", tasks=billing_plan)


# The agent that ran the group comes in, its hand_off goes out
UnmuteAgent(
    front_desk,
    state=state,
    then_targets={
        "billing": lambda agent: agent.hand_off(
            UnmuteAgent(billing, state=agent.state), announce="One moment."
        )
    },
)

billing = AgentSpec(BILLING_PROMPT, name="billing", tasks=billing_plan)


# The same handler a handoff tool has
async def to_billing(params: FunctionCallParams) -> None:
    await flows.hand_off(params, billing, announce="One moment.")


flows = UnmuteFlows(front_desk, ..., state=state, then_targets={"billing": to_billing})

1. A group whose target then_targets does not name is refused when the agent is built. On Pipecat, so is a hand_off to a spec with such a group, because one then_targets serves every agent of the call.
2. The last step’s words play first. Then the handoff runs as from a tool: its announce line, its context, and the next agent replies first. The main agent is not asked for a reply.
3. The next agent hears the main agent’s history as the group left it. That is what was said before the group, the caller turn a step carried back, and the step’s spoken closing line. The steps’ own talk stays in the group, as it does when the group returns. Saved values reach the next agent through its prompt.
4. The group’s own tool call never crosses, as a handoff tool’s call does not.
5. A group that hands the caller back, or fails, returns to the main agent instead. So does a transfer whose handoff raises, or hands nothing over. The caller is never left in silence.
6. The main agent’s tool description says that the flow does not return: “This flow does not return to you: when it finishes the caller is handed to the billing.”

​

A handoff on a plain agent

​

Troubleshooting

​

A handoff is refused while a task runs

​

hand_off needs an agent built on the same CallState.

return await self.hand_off(UnmuteAgent(specialist, state=self.state))

​

A spec with a model is refused on Pipecat

​

The next agent hands the call straight back

​

How Unmute uses handoffs

• summary works on Pipecat too. Unmute refuses it there.
• A failed summary falls back to messages. In Unmute, the handoff tool raises.
• last_n keeps a tool call whose result is in the window. LiveKit’s truncate drops it. Unmute’s Pipecat code keeps it.
• A step handoff beside another call is refused at once. Unmute waits for the other call, then refuses when it ended the step or failed.
• A group’s then: transfer and then_target map to TaskGroupSpec, and the target to then_targets. Unmute’s LiveKit code transfers a group that stopped unserved too. The library returns it to the main agent, as for then: end. Unmute’s handoff has no line and keeps the whole history. Here the handoff in then_targets decides both.
• The first reply after a handoff leaves out the new agent’s handoffs on Pipecat too. Unmute’s Pipecat code offers them.
• On Pipecat, one pipeline runs every agent. The model switches inside a ModelCallLLMService, and the voice through a VoiceSwitcher. Unmute builds one worker per agent, each with its own LLM and TTS.

​

Where to go next