> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 智能体转接

## 概览

智能体间转接允许 ElevenLabs 智能体在满足特定条件时，将正在进行的对话交接给另一个指定智能体。这样可构建多层对话 workflow，由不同智能体处理特定任务或不同复杂度的问题。

例如，初始智能体（协调器）可处理一般咨询，再根据对话上下文将通话转接给专业智能体。转接也可以嵌套：

```text
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)

```

**用途**：根据用户需求，在专业 AI 智能体之间转接对话。

**触发条件**：LLM 应在以下情况调用此工具：

* 用户请求需要专业知识或其他智能体能力
* 当前智能体无法妥善处理该查询
* 对话流程表明需要其他类型的智能体

**参数**：

* `reason`（字符串，可选）：转接智能体的原因
* `agent_number`（整数，必填）：要转接到的智能体的从零开始编号（基于已配置的转接规则）

**函数调用格式**：

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

**实现方式**：定义将条件映射到特定智能体 ID 的转接规则。配置当前智能体可转接到哪些智能体。在转接配置中，智能体以从零开始的编号表示。

## 启用智能体转接

通过 `transfer_to_agent` 系统工具配置智能体转接。

#### 添加转接工具

在 `Agent` 标签页的智能体配置中选择 `transfer_to_agent` 系统工具，即可启用智能体转接。添加工具时，选择“转接至 AI 智能体”。

![添加转接工具](/docs/_fern-img/3e2756669b192395680d48a17c622493faee9fb61649f491bbe66820a91d46ef.webp)

#### 配置工具描述（可选）

可提供自定义描述，指导 LLM 何时触发转接。若留空，将使用包含已定义转接规则的默认描述。

![转接工具描述](/docs/_fern-img/6b916200ef66cd0c6f5af7f6ba51b4b48eb1a266c7b10e863ae874c5a11452ae.webp)

#### 定义转接规则

配置转接至其他智能体的具体规则。每条规则需指定：

* **智能体**：要将对话转接至的目标智能体。
* **条件**：说明何种情况下应进行转接的自然语言描述（例如，“用户询问账单详情”“用户请求产品 X 的技术支持”）。
* **转接前延迟（毫秒）**：进行转接前的最短延迟时间（毫秒）。默认为 0，即立即转接。
* **转接消息**：转接期间播放的可选自定义消息。若留空，将静默完成转接。
* **启用首条消息**：转接后，接收对话的智能体是否应播放首条消息。默认关闭。

LLM 会结合这些条件和工具描述，决定何时以及转接给哪个智能体（按编号）。

![转接规则配置](/docs/_fern-img/b1b7e0f58ae757640af46630fde962a78ef4a164a380f974297bb643ccc29443.webp)

> **Note**
>
> 请确保创建该智能体的用户账户，对转接规则中指定的所有目标智能体至少拥有查看者权限。

## 转接行为

发生转接时，**父智能体**（发起转接的智能体）会将部分配置值传递给 **子智能体**（接收对话的智能体），而其他配置会被完全重置。

### 配置继承

无论子智能体自身配置如何，父智能体都会覆盖每个子智能体的以下值：

| 设置             | 描述                                                      |
| -------------- | ------------------------------------------------------- |
| **客户端事件**      | 客户端发送哪些事件（例如 `audio`、`interruption`、`user_transcript`）。 |
| **TTS 输出音频格式** | 发送智能体语音时采用的格式（例如 `pcm_16000`、`ulaw_8000`）。              |
| **ASR 输入音频格式** | 智能体预期接收的用户音频格式（例如 `pcm_16000`、`ulaw_8000`）。             |

此外，父智能体当前使用的语言也会一并传递；如果子智能体不支持该语言，则会回退到自己的默认语言。通话后 webhook 和分析配置（包括评估标准和数据收集项）同样适用于整个对话。

### 不继承的配置

其他所有配置均由子智能体设置，包括但不限于：

* 提示词、首条消息、LLM、workflow、音色、工具和知识库
* TTS 音色、模型、稳定性及其他音色设置（`agent_output_audio_format` 除外）
* ASR 模型、质量和关键词（`user_input_audio_format` 除外）
* 轮次/超时、语言预设、最长时长等

> **Note**
>
> 请在 workflow 的每个智能体中保持这些设置一致，以避免行为不匹配。

使用 [Realtime 模型](/docs/zh/eleven-agents/customization/realtime-models) 的智能体只能与其他使用 Realtime 模型的智能体互相转接。

### 转录文本和聊天记录

完整转录文本会在整个对话中保留。此前每个智能体的用户和智能体消息都会留在聊天记录中。

转接期间，会从子智能体 LLM 可见的历史记录中移除 `transfer_to_agent` 工具调用，使其能继续对话而不提及交接过程。

### 通话后评估

通话后评估器 LLM 会收到完整、未过滤的转录文本，包括所有用户和智能体消息，以及包括转接在内的所有工具调用。

单条消息不包含 `agent_id` 字段。评估器通过转录文本中的 `transfer_to_agent` 工具调用作为边界标记，判断哪些消息由哪个智能体生成。

## API 实现

可通过 API 创建或更新智能体时配置 `transfer_to_agent` 系统工具。

```python
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)
```

```javascript
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,
                },
              ],
            },
          },
        },
      },
    },
  },
});
```