Agent transfer | ElevenLabs Documentation

Overview

Agent-agent transfer allows a Conversational AI agent to hand off the ongoing conversation to another designated agent when specific conditions are met. This enables the creation of sophisticated, 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)

Example Agent Transfer Hierarchy

We recommend using the gpt-4o or gpt-4o-mini models when using agent-agent transfers due to better tool calling.

Enabling agent transfer

Agent transfer is configured using the transfer_to_agent system tool.

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.

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.

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”).

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.

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     PromptAgentToolsItem_System,
7     SystemToolConfig,
8     TransferToAgentToolConfig,
9     Transfer
10 )
11 
12 # Initialize the client
13 client = ElevenLabs(api_key="YOUR_API_KEY")
14 
15 # Define transfer rules
16 transfer_rules = [
17     Transfer(agent_id="AGENT_ID_1", condition="When the user asks for billing support."),
18     Transfer(agent_id="AGENT_ID_2", condition="When the user requests advanced technical help.")
19 ]
20 
21 # Create the transfer tool configuration
22 transfer_tool = PromptAgentToolsItem_System(
23     type="system",
24     name="transfer_to_agent",
25     description="Transfer the user to a specialized agent based on their request.", # Optional custom description
26     params=SystemToolConfigInputParams_TransferToAgent(
27         transfers=transfer_rules
28     )
29 )
30 
31 # Create the agent configuration
32 conversation_config = ConversationalConfig(
33     agent=AgentConfig(
34         prompt=PromptAgent(
35             prompt="You are a helpful assistant.",
36             first_message="Hi, how can I help you today?",
37             tools=[transfer_tool],
38         )
39     )
40 )
41 
42 # Create the agent
43 response = client.conversational_ai.create_agent(
44     conversation_config=conversation_config
45 )
46 
47 print(response)