Transfer to Agent

The Transfer to Agent tool hands the caller from the agent they are talking to over to another AiLunaPro agent, without dropping the call. The caller stays on the same call throughout: they hear a short handover line, then a ringer, then the next agent picks up. Use this tool to split one phone number across several focused agents — a router that picks a language or a department, a specialist that handles billing, a closer that takes payment — instead of building one large agent that tries to do everything.

Transfer to Agent vs. Call Transfer

Both tools move the caller somewhere else, but they are not interchangeable.

	Transfer to Agent	Call Transfer
Destination	Another AiLunaPro agent, by `workflow_id`	A phone number or SIP endpoint
Who answers	An AiLunaPro agent	A human, queue, or external phone system
Context	A labeled transcript of the previous agents’ conversation	Optional spoken introduction on Twilio; otherwise no conversation context is passed
Availability	Any cascade call, including web calls	Telephony only (Twilio, Telnyx, Asterisk ARI)

If the caller should end up talking to a person, use Call Transfer. If they should end up talking to another one of your agents, use this tool.

How it works

The agent calls the Transfer to Agent tool.
The current agent speaks the configured handover message in its own voice.
The caller hears a ringer while AiLunaPro prepares the destination agent.
AiLunaPro labels the available conversation as history from the previous agent, including anything the caller said during the handoff.
The destination agent takes over at its Start Call node. By default it plays that node’s greeting. With Play greeting turned off, it skips the greeting and opens with a reply based on the conversation history.

After a transfer is accepted, AiLunaPro suppresses the source agent’s next generation while the handover message and ringer play. If the transfer is refused, the agent can explain the result and continue helping the caller.

What the destination agent receives

The destination receives one historical message containing the available conversation, with a heading such as Conversation with previous agent "Reception":. Caller and agent speech are labeled separately. This applies to every handoff, with no minimum number of turns and no LLM summary call during the transfer. Earlier agents’ history stays in the same transcript across repeated transfers. Speech added while the destination is being prepared is included and marked as happening during the transfer. The destination is told that this is historical context and that the transfer is already complete. The source agent’s prompts, tool calls, and tool results are filtered out. Spoken text accompanying a tool call, such as the handover announcement, is retained. Later node transitions preserve the inherited transcript when summarizing the current agent’s own conversation.

Because context travels with the caller, the destination agent should not re-ask for information the caller already gave. Say so in its prompt.

Configuration

A Transfer to Agent tool has three settings. Everything else about how a handoff sounds is fixed.

Agent (workflow_id, required) — the id of the AiLunaPro agent to transfer to. It must belong to the same organization.
Handover message — stored as one text entry with event: "start" in definition.messages. Spoken by the current agent, in its own voice, just before the handover. Supports template variables. Maximum 500 characters. The editor starts with “Let me connect you with the right person. One moment please.” Leave it empty, or send messages: [] through the API, to hand over without saying anything.
Play greeting (play_greeting, default true) — whether the destination agent opens with its Start Call greeting. Turn it off when the destination should continue the conversation rather than introduce itself, for example an agent that greets callers on its own phone number but is also a transfer target. It then opens with a reply generated from the conversation history.

Set the handover message in the language the destination agent speaks. The default is English, which will sound wrong in front of a Portuguese or Spanish agent.

One tool per destination

Each Transfer to Agent tool points at exactly one agent. An agent that can hand the caller to three places gets three tools, and the model chooses between them the way it chooses between any other tools — by their names and descriptions. Name each tool after its destination and describe precisely when it should fire:

Name:        Transfer to Billing
Description: Hand the call to the billing agent. Call this only once the
             caller has said their question is about an invoice, a charge,
             or a refund. Do not call it for delivery or account questions.

If the model picks the wrong destination, fix the tool descriptions before you touch the prompt — the description is what it routes on.

Availability

Agent transfer works on every cascade call, including web calls, which is where it differs most from Call Transfer. It is not available on speech-to-speech (realtime) agents. The tool still registers there, but it refuses and tells the agent to keep helping the caller itself, so the call degrades into a normal conversation rather than failing silently.

Creating one

{
  "name": "Transfer to Billing",
  "category": "transfer_agent",
  "description": "Hand the call to the billing agent once the caller says their question is about an invoice, a charge, or a refund.",
  "definition": {
    "type": "transfer_agent",
    "messages": [
      {
        "event": "start",
        "type": "text",
        "text": "Let me put you through to our billing team. One moment."
      }
    ],
    "config": {
      "workflow_id": 117
    }
  }
}

The destination agent must exist before you create the tool, because the tool stores its id. When you are building a set of agents programmatically, create the destination agents first, then the tools, then the agent that routes between them.

Prompting the routing agent

Tell the agent that a turn is either spoken words or a tool call, never both.
Do not tell it to announce the transfer; the tool’s handover message already does that.
Give each destination an explicit, mutually exclusive firing condition.
End the prompt with success criteria naming which tool fires for which outcome, and stating that exactly one of them should ever fire.

See tool call guidance for the general rules.

Troubleshooting

`destination_not_found` when creating the tool

The workflow_id does not exist in your organization. A transfer can only hand the call to your own agents. Check the id on the destination agent’s settings page.

The agent says transferring is unavailable

The call is running on a speech-to-speech agent, where agent transfer is not supported. Switch the agent to a cascade model configuration, or use Call Transfer to reach a human instead.

The transfer is refused as already under way

Two transfer tools fired for the same call. Tighten the firing conditions in the tool descriptions so only one can match, and state in the prompt that exactly one transfer may happen.

The transfer is refused as misconfigured

The tool’s workflow_id is missing or is not an integer. Re-create the tool with a valid agent id.

The destination agent re-asks something the caller already answered

Check that the destination agent’s prompt tells it to use the conversation history from previous agents. Add an instruction that the caller has already spoken to a colleague and should not be asked to repeat themselves.

Getting started

Build your First Agent

Core Concepts

Configurations

Voice Agent Builder

Telephony

Integrations