Agent transfer

Overview

Agent-to-agent transfer allows an ElevenLabs agent to hand off the ongoing conversation to another designated agent when specific conditions are met. This enables multi-layered conversational workflows where different agents handle specific tasks or levels of complexity.

For example, an initial agent (Orchestrator) could handle general inquiries and then transfer the call to a specialized agent based on the conversation’s context. Transfers can also be nested:

Orchestrator Agent (Initial Qualification)
│
├───> Agent 1 (e.g., Availability Inquiries)
│
├───> Agent 2 (e.g., Technical Support)
│     │
│     └───> Agent 2a (e.g., Hardware Support)
│
└───> Agent 3 (e.g., Billing Issues)

Purpose: Transfer conversations between specialized AI agents based on user needs.

Trigger conditions: The LLM should call this tool when:

• User request requires specialized knowledge or different agent capabilities
• Current agent cannot adequately handle the query
• Conversation flow indicates need for different agent type

Parameters:

• reason (string, optional): The reason for the agent transfer
• agent_number (integer, required): Zero-indexed number of the agent to transfer to (based on configured transfer rules)

Function call format:

1
{
2
  "type": "function",
3
  "function": {
4
    "name": "transfer_to_agent",
5
    "arguments": "{\"reason\": \"User needs billing support\", \"agent_number\": 0}"
6
  }
7
}

Implementation: Define transfer rules mapping conditions to specific agent IDs. Configure which agents the current agent can transfer to. Agents are referenced by zero-indexed numbers in the transfer configuration.

Enabling agent transfer

Agent transfer is configured using the transfer_to_agent system tool.

1

Add the transfer tool

Enable agent transfer by selecting the transfer_to_agent system tool in your agent’s configuration within the Agent tab. Choose “Transfer to AI Agent” when adding a tool.

2

Configure tool description (optional)

You can provide a custom description to guide the LLM on when to trigger a transfer. If left blank, a default description encompassing the defined transfer rules will be used.

3

Define transfer rules

Configure the specific rules for transferring to other agents. For each rule, specify:

• Agent: The target agent to transfer the conversation to.
• Condition: A natural language description of the circumstances under which the transfer should occur (e.g., “User asks about billing details”, “User requests technical support for product X”).
• Delay before transfer (milliseconds): The minimum delay (in milliseconds) before the transfer occurs. Defaults to 0 for immediate transfer.
• Transfer Message: An optional custom message to play during the transfer. If left blank, the transfer will occur silently.
• Enable First Message: Whether the transferred agent should play its first message after the transfer. Defaults to off.

The LLM will use these conditions, along with the tool description, to decide when and to which agent (by number) to transfer.

Ensure that the user account creating the agent has at least viewer permissions for any target agents specified in the transfer rules.

Transfer behavior

When a transfer occurs, the parent agent (the one initiating the transfer) passes certain configuration values to the child agent (the one receiving the conversation), while others reset entirely.

Configuration inheritance

The parent agent overwrites the following values on every child agent, regardless of the child’s own configuration:

Additionally, the parent agent’s current language is carried over — if the child agent does not support it, it falls back to its own default. Post-call webhook and analysis configuration (including evaluation criteria and data collection items) also apply to the entire conversation.

Not inherited

All other configurations are set by the child agent, included but not limited to:

• Prompt, first message, LLM, workflow, voice, tools, and knowledge base
• TTS voice, model, stability, and other voice settings (except agent_output_audio_format)
• ASR model, quality, and keywords (except user_input_audio_format)
• Turn/timeout, language presets, max duration etc.

Transcript and chat history

The full transcript is preserved across the entire conversation. User and agent messages from every preceding agent remain in the chat history.

During a transfer, transfer_to_agent tool calls are stripped from the history visible to the child agent’s LLM, so it continues the conversation without mentioning the handoff.

Post-call evaluation

The post-call evaluator LLM receives the full, unfiltered transcript — all user and agent messages, and all tool calls including the transfer.

Individual messages do not carry an agent_id field. To determine which agent produced which messages, the evaluator uses the transfer_to_agent tool call as a boundary marker in the transcript.

API implementation

You can configure the transfer_to_agent system tool when creating or updating an agent via the API.

1
from elevenlabs import (
2
    ConversationalConfig,
3
    ElevenLabs,
4
    AgentConfig,
5
    PromptAgent,
6
    PromptAgentInputToolsItem_System,
7
    SystemToolConfigInputParams_TransferToAgent,
8
    AgentTransfer
9
)
10
11
# Initialize the client
12
elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")
13
14
# Define transfer rules with new options
15
transfer_rules = [
16
    AgentTransfer(
17
        agent_id="AGENT_ID_1",
18
        condition="When the user asks for billing support.",
19
        delay_ms=1000,  # 1 second delay
20
        transfer_message="I'm connecting you to our billing specialist.",
21
        enable_transferred_agent_first_message=True
22
    ),
23
    AgentTransfer(
24
        agent_id="AGENT_ID_2",
25
        condition="When the user requests advanced technical help.",
26
        delay_ms=0,  # Immediate transfer
27
        transfer_message=None,  # Silent transfer
28
        enable_transferred_agent_first_message=False
29
    )
30
]
31
32
# Create the transfer tool configuration
33
transfer_tool = PromptAgentInputToolsItem_System(
34
    type="system",
35
    name="transfer_to_agent",
36
    description="Transfer the user to a specialized agent based on their request.", # Optional custom description
37
    params=SystemToolConfigInputParams_TransferToAgent(
38
        transfers=transfer_rules
39
    )
40
)
41
42
# Create the agent configuration
43
conversation_config = ConversationalConfig(
44
    agent=AgentConfig(
45
        prompt=PromptAgent(
46
            prompt="You are a helpful assistant.",
47
            first_message="Hi, how can I help you today?",
48
            tools=[transfer_tool],
49
        )
50
    )
51
)
52
53
# Create the agent
54
response = elevenlabs.conversational_ai.agents.create(
55
    conversation_config=conversation_config
56
)
57
58
print(response)