Agent transfer

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:

{
  "type": "function",
  "function": {
    "name": "transfer_to_agent",
    "arguments": "{\"reason\": \"User needs billing support\", \"agent_number\": 0}"
  }
}

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.

Agent transfer is configured using the transfer_to_agent system 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.

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.

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.

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.

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.

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.

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.

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.

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

from elevenlabs import AgentConfig, ConversationalConfig, ElevenLabs

elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")

# Define transfer rules with new options
transfer_rules = [
    {
        "agent_id": "AGENT_ID_1",
        "condition": "When the user asks for billing support.",
        "delay_ms": 1000,  # 1 second delay
        "transfer_message": "I'm connecting you to our billing specialist.",
        "enable_transferred_agent_first_message": True,
    },
    {
        "agent_id": "AGENT_ID_2",
        "condition": "When the user requests advanced technical help.",
        "delay_ms": 0,  # Immediate transfer
        "transfer_message": None,  # Silent transfer
        "enable_transferred_agent_first_message": False,
    },
]

response = elevenlabs.conversational_ai.agents.create(
    conversation_config=ConversationalConfig(
        agent=AgentConfig(
            first_message="Hi, how can I help you today?",
            prompt={
                "prompt": "You are a helpful assistant.",
                "built_in_tools": {
                    "transfer_to_agent": {
                        "type": "system",
                        "name": "transfer_to_agent",
                        # Optional custom description
                        "description": "Transfer the user to a specialized agent based on their request.",
                        "params": {
                            "system_tool_type": "transfer_to_agent",
                            "transfers": transfer_rules,
                        },
                    }
                },
            },
        ),
    ),
)

print(response)

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient({
  apiKey: "YOUR_API_KEY",
});

await elevenlabs.conversationalAi.agents.create({
  conversationConfig: {
    agent: {
      firstMessage: "Hi, how can I help you today?",
      prompt: {
        prompt: "You are a helpful assistant.",
        builtInTools: {
          transferToAgent: {
            type: "system",
            name: "transfer_to_agent",
            description: "Transfer the user to a specialized agent based on their request.", // Optional custom description
            params: {
              systemToolType: "transfer_to_agent",
              transfers: [
                {
                  agentId: "AGENT_ID_1",
                  condition: "When the user asks for billing support.",
                  delayMs: 1000, // 1 second delay
                  transferMessage: "I'm connecting you to our billing specialist.",
                  enableTransferredAgentFirstMessage: true,
                },
                {
                  agentId: "AGENT_ID_2",
                  condition: "When the user requests advanced technical help.",
                  delayMs: 0, // Immediate transfer
                  // transferMessage omitted for a silent transfer
                  enableTransferredAgentFirstMessage: false,
                },
              ],
            },
          },
        },
      },
    },
  },
});