Retell AI：拟人化实时语音 Agent

为什么需要 Retell AI：语音管道工程复杂 → 一行代码接入

传统方式构建语音 Agent 需要自行串联 ASR、LLM、TTS 三个环节，并额外处理看似简单实则困难的问题：用户说话中途打断时如何让 TTS 立刻停止？如何判断“用户停顿时长超过 800ms 就该让 Agent 回应”？如何把三方组件的流式音频在毫秒级对齐？这些工作涉及 WebRTC 音频传输、静音检测、缓存策略与网络抖动缓冲，自研通常需要数周时间。更关键的是，传统 IVR 的按键导航体验与今日用户对“自然对话”的预期严重脱节。

Retell AI 将上述管道封装为托管服务，提供两个核心服务：一是 Web 控制台，可以在不写代码的情况下配置 Agent 的提示词、语音音色、大模型参数并直接拨号测试；二是 WebSocket API，允许开发者用自定义代码接管对话逻辑——收到用户语音转写文本、调用 LLM 生成回复、推回 TTS 音频。一套管道内部完成 VAD、打断、缓冲与对齐，开发者唯一需要关注的是业务逻辑。

与 Vapi、Bland.ai 等同类工具相比，Retell AI 的核心差异在于动态端点（Dynamic Endpoint）架构：Agent 的交互逻辑可以指向开发者自己托管的任意 WebSocket 服务，这意味着业务逻辑不锁定在平台内，模型选择、RAG 检索、数据库查询都在你自己的服务器上执行，平台只做音频转换与传输。

安装与环境配置：3 步就绪

步骤一·安装 SDK。 Retell AI 提供 Python（retell）与 Node.js（retell-sdk）两个官方 SDK，按项目语言二选一安装即可。SDK 是 REST API 的封装，用于管理 Agent、创建 Phone Number、发起通话；通话中的实时音频流走 WebSocket，不需要额外安装依赖。

步骤二·获取 API Key 并配置环境变量。 登录 Retell Console（platform.retellai.com），在“设置 → API Key”页面创建密钥。免费额度下创建 Agent 不扣费，只有实际通话分钟数计费。将 Key 写入环境变量 RETELL_API_KEY，避免硬编码在代码中。

步骤三·验证连通性。 用 SDK 调用 agent.list() 或 agent.create() 接口，返回 200 且能列出已有 Agent 即表示配置成功。首次创建 Agent 需要一个 llm_websocket_url 或配置托管 LLM（如 gpt-4o-mini），最简单的验证是只传 llm_id。

# 安装 Python SDKpip install retell # 安装 Node.js SDKnpm install retell-sdk # 配置环境变量（写入 ~/.zshrc 或 .env）export RETELL_API_KEY="your_api_key_here"

快速上手：15 分钟跑通第一通电话

最小可用流程的思路：创建 Agent → 绑定/注册电话号码 → 拨号验证。如果只想验证语音链路而不注册真实号码，可以直接在 Retell Console 的“Playground”页面选择已创建的 Agent 并点击对话按钮，页面会打开麦克风权限，实时演示“用户说话 → Agent 回复”的完整链路。Playground 是零代码验证的最佳入口，适合先确认提示词与音色效果，再进入代码集成阶段。

对于需要代码集成或测试电话呼入的场景，按以下步骤操作：

1. 在 Retell Console 创建 Agent：进入“Agents”页面，点击“Create Agent”，选择“LLM Provider”为 Retell 托管的 gpt-4o-mini，在“General Prompt”中填写系统提示词（例如：“你是前台接待员，负责记录访客的姓名与来访事由”），选择音色后保存，记录生成的 Agent ID。

2. 注册电话号码：进入“Phone Numbers”页面，点击“Buy Number”购买一个美国或加拿大号码（按需，也可先跳过此步用 Playground 测试）。

3. 用 SDK 发起测试：调用 client.call.create() 并传入 to_number 与 from_number，Retell AI 会拨通目标电话；若使用 Playground，则无需此步。

完成以上步骤后，你会接到一通真实电话，电话那头是 Retell AI 合成的语音 Agent。进阶技巧：在 Console 的“Agent → General Prompt”中修改提示词后保存，再次拨号即可验证新对话行为，无需重新部署任何代码。

from retell import Retell client = Retell(api_key="your_api_key_here") # 列出已有 Agent，验证连通性agents = client.agent.list()print(agents) # 发起一通电话（需已购买号码）response = client.call.create(    to_number="+14155551234",    from_number="+14155559876",    agent_id="your_agent_id")print(response.call_id)

核心能力详解：4 大支柱

支柱一·动态端点（Dynamic Endpoint）WebSocket 协议。 这是 Retell AI 与多数竞品最大的差异。开发者自行托管一个 WebSocket 服务，接收平台推送的 transcript 事件（含用户语音转写结果与时间戳），在服务端调用任意 LLM（OpenAI、Anthropic、本地模型均可）生成回复，再以 response 事件传回文本。协议定义了 transcript、response、agent_start_talking、agent_stop_talking、realtime_input 等事件类型，其中 realtime_input 用于传递中间转写结果与音频流，实现端到端延迟控制。动态端点意味着业务逻辑完全掌控在开发者手中，不依赖平台的模型托管能力。

支柱二·托管 LLM 与语音配置。 平台原生托管 gpt-4o、gpt-4o-mini、claude-3.5-sonnet 等模型，开发者可指定 llm_id 将 Agent 的对话大脑直接托管在平台侧，省去自建 WebSocket 服务。语音配置包括音色选择（供应商 ElevenLabs、OpenAI TTS、Azure TTS 等）、语速、音量、停顿敏感度（end_call_after_silence_ms）、最大响应时长等参数。托管模式下，提示词（General Prompt）直接在 Console 配置，适合业务逻辑简单的场景；动态端点则适合需要检索增强、数据库查询、权限控制等复杂场景。

支柱三·工具调用与函数执行。 在动态端点模式下，开发者可以在 WebSocket 服务中定义函数（如查询订单状态、创建工单），LLM 输出结构化函数调用参数，服务端执行后把结果追加到上下文再让 LLM 生成最终回复。这使语音 Agent 从“问答机器人”升级为“能办事的数字员工”。函数执行天然支持异步任务，例如通话中触发 CRM 写入，不阻塞对话流。

支柱四·低延迟实时传输与打断处理。 Retell AI 的通话延迟（用户说完到 Agent 开始回复）平均在 500-800ms 区间，由平台侧完成 VAD 与端到端流式处理。打断处理是语音体验的核心：用户说话时 Agent 的 TTS 必须能被立即截断，平台通过连续监听半双工/全双工音频流并在检测到人声时立即发送 interruption 信号来实现。这一层工程复杂度完全被平台吸收，开发者无需关心 WebRTC 与音频缓冲细节。

生产部署与监控：从上线到运维

部署方式一·动态端点服务。 生产环境应将 WebSocket 服务部署在延迟离 Retell 数据中心较近的云区域，官方建议美东或美西，并启用自动扩缩容。由于动态端点本质是普通 WebSocket 服务，可直接部署在 Railway、Render、Fly.io 等 PaaS 平台，或容器化后部署到 ECS/GKE。需要关注连接数上限，单个实例建议不超过 500 并发连接（视语言运行时与 LLM 调用耗时而定），超限时通过水平扩容解决。

部署方式二·电话线路接入。 Retell AI 提供两种电话接入方式：购买平台号码（Console 一键购买，支持美国和加拿大）或携带自有 SIP 中继。企业已有 400 号码或 SIP 线路时，可通过 SIP 对接把现有号码转入 Retell AI 处理。号码侧需要配置应用路由（Routing），把来电分发到指定 Agent。电信合规方面，美国市场需注意 TCPA（电话消费者保护法）对自动外呼的同意要求，平台提供 DNC（拒接电话登记）支持但合规责任在业务方。

可观测性。 平台提供三大类监控数据：通话明细（每个 call 的转写全文、事件时间戳、延迟分段）、费用明细（按分钟计费的按 Agent 聚合报表）、质量评分（基于延迟与中断率的健康分）。生产环境建议将 call.metadata 中写入业务侧 ID（如订单号、用户 ID），便于在 Console 按 metadata 过滤检索通话记录。平台也支持 Webhook 推送通话结束事件，可用于对接工单系统或质检流程。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>忽略 VAD 参数导致响应迟钝：默认停顿敏感度偏保守，通话场景建议将 end_call_after_silence_ms 调至 600-1000ms 并测试不同音色的实际停顿节奏，否则用户会觉得 Agent “反应慢半拍”。</li><li>动态端点未做重连与超时处理：平台 WebSocket 会因网络抖动断开连接，必须在服务端实现心跳重连与 30 秒无响应自动关闭通话，否则通话会“死寂”到超时才挂断。</li><li>把动态端点写到 Console 而不用代码管理：生产环境应通过 API/SDK 创建 Agent（将 llm_websocket_url 指向你的服务），Console 手改提示词会导致配置漂移，上线后无法追溯变更。</li><li>TTS 厂商配额未评估：音色供应商另有独立配额，高并发时段可能触发限流使 Agent 静默，需为音色供应商单独配置告警。</li><li>未设置通话超时上限导致费用失控：意外场景（用户不挂断且 Agent 持续说）会产生长通话，应在 Agent 配置中设置 max_call_duration_ms。</li></ul>

版本迭代

Retell AI 自 2023 年推出后经历了从 v1 到 v2 的协议升级，核心方向是“从平台托管逻辑走向开发者自定义逻辑”。v1 以托管 LLM 为主，v2 引入动态端点，将对话控制权全面移交开发者；此后迭代集中在延迟优化与工具调用增强。（截至训练数据，可能已有更新版本）

AI 应用场景

常见误区

面试题