# 语音 Agent 在笔记本上会让人打断，说明不了什么

> 用 LiveKit 搭一条保险热线：法律声明不被打断，来电者能插话，转人工走客户的 SIP 中继。

原文: https://fdetimes.net/zh/guides/livekit-voice-agent-interruptions-call-transfer/

你在笔记本上打断 Agent，它应声就停。可一旦 Agent 搬到客户的环境里，打断的表现可能就不再如你所料，因为 LiveKit 的自适应打断只在特定条件下才默认开启。

这类小细节，正是演示和能接真实来电的系统之间的差别。本指南不止于大模型怎么回答，而是关注真实通话里会遇到的情况：客户说到一半咳嗽，客户中途插话，客户要求转人工。

如果你是前线部署工程师（FDE），这部分正是你要向客户运维团队讲清楚的。

## 要搭什么，需要准备什么？

设想一条保险热线（假设场景）。Agent 要念一段不能被打断的法律声明，回答问题，允许客户插话，并在客户要求时把电话转给工作人员。

LiveKit 文档要求 Python 3.10 或更高版本，快速入门用 uv 管理依赖。动手之前先检查这两项：

```bash
python3 --version
uv --version
```

**检查：**Python 必须是 3.10 或更高版本。下面的代码为便于说明做了简化，项目脚手架、安装步骤和完整参数名请以 LiveKit 文档为准。

## 第 1 步：把三家服务商接进一个会话

按照快速入门，Agent 通过 LiveKit Inference 接入 STT、LLM 和 TTS 三家独立的服务商，再用 `AgentSession` 包起来。客户抱怨 Agent 听错或说话慢时，首先要查的就是这三个环节。

```python
from livekit.agents import AgentSession

# 简化示例：需按快速入门补全后才能运行
session = AgentSession(
    stt="<STT model>",
    llm="<LLM model>",
    tts="<TTS model>",
    # 在此添加 VAD 模型，声明方式见快速入门
)
```

上面的代码还不是一个能运行的 Agent。你需要从快速入门里补上四样东西：用 uv 创建项目和安装依赖的命令，替换占位符的 STT、LLM 和 TTS 模型名，启动 Agent 和会话的代码，以及声明 VAD 模型的方式。

**检查：**四部分都补齐后，文件运行时不应出现导入错误。不要漏掉 VAD 模型：它是自适应打断默认开启的条件之一，第 3 步的测量也依赖它。

## 第 2 步：用 console 模式试听，但别急着下结论

快速入门提供了 console 模式，直接在终端里运行 Agent，和 dev 模式是两回事。要听提示词效果，console 最快。

```bash
# 简化示例：文件名取决于你的项目，完整语法见快速入门
uv run agent.py console
uv run agent.py dev
```

只有 Agent 已部署到 LiveKit Cloud，或在带 Cloud 凭据的 dev 模式下运行，并且会话配有语音活动检测（VAD）模型时，自适应打断才默认开启。console 不在这两种情况之列，不要用它来判断打断行为。

**检查：**在两种模式下分别打断 Agent，记下差异。打断测试应在带 Cloud 凭据的 dev 模式下进行，或者就在将来上生产环境的那个环境里进行。

**要点:** 打断测试只有在与生产环境相同的模式下运行，才算数。

## 第 3 步：靠测量选择打断处理方式

有两个问题很容易混为一谈：客户说完了没有？客户是不是真想打断 Agent？对于第一个问题，纯 VAD 只看静音，咳嗽或线路噪声都可能触发它。

LiveKit 针对这个问题推荐使用轮次检测模型（turn detector），因为它直接分析语音，把说话内容和语调、节奏等声学信号结合起来判断。对于第二个问题，自适应打断的设计目标是在客户抢话时让 Agent 自然地作出反应。

不用自适应的话，轮次处理设置里还有两个选项。下面的代码只示意要设置的值，并非准确语法：

```python
# 示意：类名及如何传入会话请参阅 LiveKit 文档
turn_handling = {"interruption": {"mode": "vad"}}     # 仅用 VAD
turn_handling = {"interruption": {"enabled": False}}  # 完全关闭打断
```

除了关于轮次检测模型的推荐，下表的建议都针对这条假设的热线，并非 LiveKit 的规定：

| 选项 | 作用 | 适用情况 | 注意事项 |
|---|---|---|---|
| 轮次检测模型 | 预测客户是否已说完 | 希望 Agent 听得自然 | 仍需用客户自己的音频测量 |
| 自适应 | 处理客户抢话 | 满足 Cloud 和 VAD 条件，且客户经常插话 | 运行环境一变就要重新确认，可能不再默认开启 |
| `mode: "vad"` | 处理客户抢话 | 需要一个简单、好解释的机制 | 咳嗽或线路噪声可能让 Agent 误停 |
| `enabled: false` | 完全关闭打断 | 单向播报流程 | 客户无法打断 Agent |

不要凭耳朵选，但也别急着测。先确认 Agent 在带 Cloud 凭据的 dev 模式下运行或已部署到 Cloud，并且会话配有 VAD 模型。只要缺一个条件，“默认”配置就可能不是自适应，你的对比表也会把你引向错误结论。

然后录 10 段带咳嗽的音频和 10 段客户真正插话的音频，存成文件，保证每轮测试用的音频完全一样。

一个不需要额外 API 的简化方法：让 Agent 念一句固定的长句，在它念的过程中，用手机对着笔记本麦克风逐个播放这些文件。音量和距离保持不变，记下 Agent 是否停下。然后只改一个配置参数，按完全相同的流程再来一遍。

轮次检测模型回答的是另一个问题，需要单独测试。录下客户说到一半停下来思考的音频，统计 Agent 在客户说完之前抢先回答的次数。

举一组示意数字：配置 A 在 10 次咳嗽中停了 6 次，10 次真实插话全部停下；配置 B 分别是 1 次和 8 次。A 会让 Agent 频频卡顿，惹客户心烦；B 则有 2 成的情况要客户再说一遍。有了这份统计，客户面对的是代价清楚的选择，而不是一句“听起来会很自然”的承诺。

**检查：**你手上有一张统计表，每种配置一行，记录 Agent 运行在哪里、会话是否配有 VAD，以及 10 次咳嗽和 10 次真实插话中 Agent 各停了几次。

## 第 4 步：只对一句话关闭打断，而不是整通电话

法律声明就是不能被打断的情况。在 Python 中，LiveKit 文档允许给 `say()` 或 `generate_reply()` 传入 `allow_interruptions=False`，只对这一句关闭打断。

```python
await session.say(
    "为保证服务质量，本次通话将被录音。",
    allow_interruptions=False,
)
```

**检查：**在这句话播放时插话，Agent 必须念完；接着在下一个回答播放时插话，Agent 必须作出反应。如果两次都不停，你可能在会话级别关闭了打断。

## 第 5 步：客户要求转人工，热转接还是冷转接？

两种转接的区别在于上下文由谁掌握。冷转接把来电者转到另一个电话号码或 SIP 端点，随后来电者的 LiveKit 会话结束。因此，需要保留的内容，比如通话记录或转接原因，都应在转接前保存好。

热转接是 Agent 先呼叫工作人员，概述情况，再把双方接通。现成的方案是 `WarmTransferTask`，在 Python 中它仍位于 `beta.workflows` 下。这个任务需要一条出站 SIP 中继，可以直接声明，也可以通过已保存的中继 ID 指定。

```python
# 简化示例：导入路径和其余参数见 WarmTransferTask 文档
from livekit.agents.beta.workflows import WarmTransferTask

task = WarmTransferTask(
    sip_trunk_id="<outbound trunk id>",  # 或 sip_connection=...
    # 目标号码、概要上下文：按文档填写
)
```

在这条假设的热线上，投诉理赔的客户应走热转接，因为没人愿意把经过再讲一遍。只需转到其他部门办简单事务的客户，可以走冷转接。

**检查：**通过真实中继拨一通测试电话。热转接时，工作人员必须在接通前听到概要；冷转接时，确认电话到达了正确的目标，并且数据在会话结束前已保存。

## 一开始就要避开的三个错误

最容易犯的错误，是为了不让 Agent 遇到咳嗽就卡顿，干脆关闭整个会话的打断。症状是没了，可客户也失去了打断一台说错话的机器的权利。

第二个错误出在服务商，而不在代码。如果服务商的中继不允许呼叫转移，比如 Twilio 上的 SIP REFER，冷转接就会失败，所以第一周就要检查这项配置。

最后一个错误是把 beta API 当成稳定 API。`WarmTransferTask` 在 Python 中仍处于 beta 分支，要锁定库的版本，每次升级都重跑转接测试。

## 到了客户现场，第一个问题与模型无关

先问三个问题：Agent 运行在哪里？SIP 中继由谁管理，是否允许呼叫转移？Agent 转接时由谁接听？第一个问题决定自适应是否默认开启，第二个问题通常要找客户的电信团队，第三个问题决定概要该发给谁。

浏览语音方向的 FDE 岗位描述时，留意 telephony、SIP、contact center 这类词。简历上，一句具体的描述比“具备语音 AI 经验”更有说服力：写明你测量用的音频集、调整配置前后 Agent 的误停率，以及一次在真实中继上跑通的热转接。

声音好不好听，说明不了语音 Agent 的好坏。要看的是客户插话那一秒它怎么反应，以及必须让位给人工的那一秒它怎么做。

**本周动手试试:**

- 按快速入门搭好 Agent，先在 console 中运行，再在带 LiveKit Cloud 凭据的 dev 模式下运行，记下打断时的差异。
- 确认 Agent 满足 Cloud 条件并配有 VAD 模型，然后在 vad 模式和默认模式下各测 10 次咳嗽和 10 次真实插话，把结果整理成表格写进 README。
- 列一份问客户的问题清单，涵盖部署位置、SIP 服务商、中继的转接权限，以及转接后由谁接听。

## 信源

- [Voice AI quickstart (LiveKit docs)](https://docs.livekit.io/agents/start/voice-ai-quickstart/)

- [Adaptive interruption handling (LiveKit docs)](https://docs.livekit.io/agents/logic/turns/adaptive-interruption-handling.md)

- [Turns overview (LiveKit docs)](https://docs.livekit.io/agents/build/turns/)

- [Configuring turn detection and interruptions in LiveKit Agents](https://livekit.com/blog/turn-detection-and-interruption-handling)

- [WarmTransferTask (LiveKit docs)](https://docs.livekit.io/agents/prebuilt/tasks/warm-transfer.md)

- [Cold transfer (LiveKit telephony docs)](https://docs.livekit.io/sip/transfer-cold.md)
