The Agent Transfer function (type: "agent_swap") hands the conversation to another agent in your workspace without a new phone leg. The call keeps its call_id, its transcript and the variables collected so far. The new agent's prompt, tools, flow and settings take over from the next turn.
Use it to split a large agent into specialists: a receptionist that routes to a bookings agent, a billing agent or an after-hours agent. Unlike a call transfer, nothing is dialled and it also works in web calls.
Configure in the dashboard#
- Open the agent, expand Functions, click Add and choose Agent Transfer.
- Set Name and Description. The default description is "Hand the call to another agent when the caller needs it."
- Pick the Agent. Save stays disabled until an agent is selected.
- Set Keep current voice (on by default) and Keep current language.
- Optional: Speak during execution and Typing sound under While it runs.
- Click Save.
Fields#
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type |
"agent_swap" |
Yes | ||
name, description |
string | name yes | See overview | |
agent_id |
string | Yes | Agent to switch to | |
agent_version |
integer | No | latest | Pin a version of the target agent |
keep_current_voice |
boolean | No | true |
Keep speaking with the current voice instead of the new agent's voice |
keep_current_language |
boolean | No | Saved with the tool. The current worker applies only keep_current_voice |
|
speak_during_execution |
boolean | No | Say something before switching | |
execution_message_description |
string | No | What to say |
{
"type": "agent_swap",
"name": "go_to_bookings",
"description": "Hand the call to the bookings agent when the caller wants to book, move or cancel an appointment.",
"agent_id": "agent_3fa2...",
"keep_current_voice": true
}What happens when it runs#
Load the new agent#
The worker asks the API to switch the call. The call record's agent_id and agent_version change to the target, and an agent_swap event is stored with former_agent_id, new_agent_id and new_agent_version.
Reset the position#
A multi-prompt target starts in its starting_state (or its first state). A conversation-flow target starts at its start node.
Keep the context#
The transcript so far and the collected dynamic variables carry over. The new agent sees the whole conversation.
Voice#
With Keep current voice off, the worker switches the text-to-speech voice to the new agent's voice.
Reply#
The new agent generates the next turn with its own prompt.
If the switch fails (for example the agent does not exist), the LLM gets "Error: agent swap failed" and the current agent continues.
Agent transfer vs call transfer#
| Agent transfer | Call transfer | |
|---|---|---|
| New phone leg | No | Yes |
| Works in web calls | Yes | No |
call_id |
Same | Same for the caller; agentic warm adds a separate leg |
| Who talks next | Another Tried agent | A person or external number |
| Billing | One call | Transfer legs are added as cost lines |
In conversation flows#
Flows have an Agent Transfer node (type: "agent_swap") that switches at a fixed step and has a Swap failed edge. See Agent transfer node.
Gotchas#
- The new agent generates its next turn from its prompt; it does not start over with a greeting flow. Write its prompt to pick up from a handover ("The caller was just transferred to you from reception").
- The call record points at the new agent from the switch onwards, and its model, knowledge bases and functions are used for the rest of the call.
- Pin
agent_version(API only) when you want the target to stay on a tested version.