Hand off calls to another voice agent
Let a Voice Agent pass a live call to another Voice Agent in your workspace, keeping the voice and model but switching to the other agent's prompt and tools.
The Agent Handoff function lets one Voice Agent pass an ongoing call to another Voice Agent. Use it to build a team of specialists, for example a front-desk agent that hands callers to a billing agent or a booking agent.
How a handoff works
When the source agent calls the function, the call continues without a hang-up or a new connection.
- Kept from the source agent: the voice, the speech-to-text and text-to-speech settings, and the language model. The call keeps this agent's voice and model.
- Taken from the destination agent: the instructions, the welcome message, and the Knowledge Base.
- Tools: the call keeps the source agent's functions and adds the destination agent's functions. If both have a function with the same name, the destination's version is used.
- Conversation: the conversation so far carries over, so the destination agent knows what the caller already said.
- Further handoffs: the destination agent does not inherit the source agent's handoff functions. It can hand off only if you give it its own Agent Handoff function.
Create an Agent Handoff function
- Open the source Voice Agent and select Functions in the sidebar.
- Select Create Function.
- Select Agent Handoff.
- Fill in the form.
- Select Create Function.
| Field | What to enter |
|---|---|
| Function Name | The default is handoff_to_agent. Use a distinct name per destination. |
| Description | When the agent should hand off. The default is "Use this function when the user's request should be handled by the destination agent." |
| Pre-Tool Execution Message (Optional) | What the agent says before the handoff, such as "Let me connect you to our billing specialist." |
| Destination Agent | The Voice Agent that takes over. The current agent is not in the list. |
Write a description that names the caller requests that belong to the destination agent.
Use this function when the caller asks about invoices, refunds, or payment problems.
Rules
- You can create one handoff function for each destination agent from a source agent.
- The function name must be unique for the source agent.
- Hand off to agents that you have created in the same workspace.
Manage the function
The Functions page lists the function as Agent Handoff. Select the edit icon to change it, or the delete icon to remove it.
Test a handoff
- Save both agents.
- On the source agent, select Test Agent and choose Web Call.
- Ask for something the destination agent handles. The agent speaks the pre-tool message and then answers with the destination agent's instructions.
Handoff results appear in the call details on the Call Logs page.
Troubleshooting
The agent does not hand off. Make the description more specific, and check that the function appears in the Functions list of the source agent.
The destination agent cannot use a function I expected. The destination uses its own functions plus the source agent's. Add the function to the destination agent.
The destination agent sounds different from its own configuration. This is expected. The call keeps the source agent's voice and model. Only the prompt, welcome message, Knowledge Base, and tools change.
Frequently asked questions
Can I build a multi-agent team from a template? Yes. See Create voice agents from multi-agent templates.
Can the destination agent hand the caller back? Yes. Add an Agent Handoff function to the destination agent that points back to the first agent.
Related Articles