Handoffs

A handoff moves the caller from one agent to another. The receiving agent owns the rest of the call. Nothing returns automatically. Use a handoff when two roles need different instructions, tools, or permissions. Use a task when the work should return control to the same agent. On this page:

Declare and attach a handoff - the two blocks
Every key a handoff takes - all four
Share only intentional saved values - saving is not sharing
Choose conversation history - what travels with the caller
A handoff does not return - the one thing to remember

Declare and attach a handoff

agent.yaml

entry_agent: booking_desk

agents:
  booking_desk:
    instructions: instructions.md
    think: reasoning
    speak: voice
    handoffs:
      - to_appointment_manager

  appointment_manager:
    instructions: agents/appointment-manager.md
    think: reasoning
    speak: voice

handoffs:
  to_appointment_manager:
    to: appointment_manager
    when: The caller wants to change an existing appointment.
    announce: I’m connecting you with our appointment manager now.

Every key a handoff takes

string

required

An existing agent name. The conversation moves to that agent and does not return. No destination is inferred.

string

The situation the model reads to decide whether to hand over. Omission supplies no trigger guidance, so write one.

string

Exact text spoken before handing over. Omit for a silent handoff.

object

The history fields. Omitted means messages. Saved values are visible only where the receiving prompt names them.

Declare a value once and reference it in the receiving prompt:

agent.yaml

variables:
  appointment_id:
    type: Id
    description: The appointment selected during this call.

agents/appointment-manager.md

You are handling appointment {{appointment_id}}.
Ask what the caller wants to change.

The receiving agent gets the saved appointment_id because its prompt names it. It does not receive other variables automatically. A dotted placeholder sends only that field. With messages, it can also read facts spoken earlier. To avoid repeating verification or asking for an appointment already selected, reference the saved verification status and appointment in the receiving prompt, then explain how to use them. The context guide walks through this choice and the return behavior of tasks.

Choose conversation history

History defaults to messages when context or history is omitted.

agent.yaml

handoffs:
  to_appointment_manager:
    to: appointment_manager
    when: The caller wants to change an existing appointment.
    context:
      history: reset

`history`	The receiving agent gets
`messages`	Earlier caller and agent speech, without tool records.
`full`	Earlier speech and paired tool records, without old instructions.
`last_n`	The newest bounded entries.
`reset`	No earlier conversation.
`summary`	A generated summary on LiveKit only.

With reset, no trigger sentence or automatic briefing is added. Save the needed facts before the handoff and reference them in the receiving prompt. If a needed fact was not saved, the receiver asks the caller. messages keeps spoken content. It is useful context sharing, not transcript redaction.

A handoff does not return

The second agent owns the call from that point. Returning to the first agent is another declared handoff in the opposite direction. When a task invokes a handoff, that task and the remaining task-group steps end before the receiving agent starts. On LiveKit, the receiving agent’s own handoffs are hidden for its first automatic turn. They return on the next caller turn. This prevents two agents from bouncing the call before the caller hears anything.

Try it

The salon is the shipped example with a handoff in each direction between the concierge and the complaint specialist. These commands need a clone of the unmute repo:

unmute validate examples/salon-concierge
unmute dev examples/salon-concierge --target pipecat

Choosing a structure

Tools, tasks, task groups, or a second agent: which split to reach for, and what it costs.

Where to go next

Tasks

When control should come back instead.

Choosing a structure

Task, task group or handoff, and what each one costs.

Context scope

Deciding what the receiving agent should be able to read.

Human transfers

Handing the caller to a person, which is a different thing.

Get started

Build the agent

Best practices

Run and observe

Optimization

Deploy

Phone calls

Targets and models

Configuration files

CLI

Community

Releases

Declare and attach a handoff

Every key a handoff takes

Choose conversation history

A handoff does not return

Try it

Choosing a structure

Where to go next

Tasks

Choosing a structure

Context scope

Human transfers

​Declare and attach a handoff

​Every key a handoff takes

​Share only intentional saved values

​Choose conversation history

​A handoff does not return

​Try it

Choosing a structure

​Where to go next

Tasks

Choosing a structure

Context scope

Human transfers

Declare and attach a handoff

Every key a handoff takes

Share only intentional saved values

Choose conversation history

A handoff does not return

Try it

Where to go next