Agent Handoffs

Agent handoffs let you split complex workflows across specialized agents. The primary agent detects intent and calls a function_tool to hand control to the right agent, which completes the request.

Handoff vs Transfer

“Handoff” and “transfer” are easy to confuse. They differ in who receives the conversation and whether context is passed along.

Term	Conversation moves to	Context passed	Covered in
Agent Handoff	Another AI agent in the same session	Optional, via `inherit_context`	This page
Agent Transfer (Call Transfer)	A human or another phone number, connected immediately	No	Call Transfer

In short: a handoff between agents keeps the conversation with the bot and only switches which agent is in control. A transfer hands the live call to a person. A transfer is cold when the person is connected with no briefing, and warm when they receive context before the call connects. When switching agents, the inherit_context flag controls whether the new agent is aware of the previous conversation.

Value	Behavior	When to Use
`inherit_context=True`	The new agent receives the full chat context.	Maintaining continuity so the user does not repeat information.
`inherit_context=False` (default)	The new agent starts with a fresh state.	Switching to a completely unrelated task.

Example

A travel agent hands off to a booking specialist from a function tool, passing the conversation context along. The handoff is driven by the tool’s return value: return the next Agent instance (constructed with inherit_context=True).

from zrt import Agent, function_tool

class TravelAgent(Agent):
    def __init__(self):
        super().__init__(
            agent_id="travel",
            instructions="You are a travel assistant. Help with travel questions and guide users to booking.",
        )

    @function_tool()
    async def transfer_to_booking(self) -> Agent:
        """Transfer the user to a booking specialist."""
        # Returning an Agent instance performs the handoff;
        # inherit_context=True passes the existing chat context.
        return BookingAgent(inherit_context=True)

class BookingAgent(Agent):
    def __init__(self, inherit_context: bool = False):
        super().__init__(
            agent_id="booking",
            instructions="You are a booking specialist. Help users book or modify reservations.",
            inherit_context=inherit_context,
        )

inherit_context controls whether the receiving agent starts with the full chat context (continuity) or a clean slate (unrelated task).

Get started

Modalities

Configure Pipeline

Tools and Capabilities

Turn Detection and Interruptions

Telephony Agents

Context Management

Observability and Monitoring

Handoff vs Transfer

Example

What’s Next

Context Window

Context Management

References

Examples

Multi-Agent Switch

SDK Reference

Function Tool

​Handoff vs Transfer

​Context Sharing

​Example

​What’s Next

Context Window

Context Management

​References

​Examples

Multi-Agent Switch

​SDK Reference

Function Tool

Handoff vs Transfer

Context Sharing

Example

What’s Next

References

Examples

SDK Reference