Agent transfer

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)

Custom LLM integration

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

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