LiveKit Agents

LiveKit Agents 快速入门：让语音助手真正「进房间」

这是什么？适合谁？

LiveKit Agents 是 LiveKit 开源的实时 Agent 框架。官方给的定位很具体：「The Agents framework lets you add any Python or Node.js program to LiveKit rooms as full realtime participants」——它不教你写对话逻辑，它解决的是你的程序怎么成为一个能听、能说、能被打断的实时参与者。

这件事听着简单，做起来是三个硬工程问题叠在一起：

1. 媒体：音频帧怎么进、怎么出、延迟多少、丢包怎么办——这是 WebRTC 层的活；
2. 模型编排：STT → LLM → TTS 三段怎么串、谁先谁后、什么时候该等用户说完；
3. 会话行为：打断（interruption）、轮次检测（turn detection）、工具调用、任务交接（handoff）。

LiveKit Agents 的做法是把这三层拆成框架能力：房间与轨道由 LiveKit（WebRTC 基建）负责；三段式管线或实时模型由框架的 AgentSession 编排；打断、轮次、工具、任务在文档里各有专章。产出物就是一个普通的 Python/Node 程序——你写的是业务，不是音频管道。

官方给的两条管线，选一条即可：

• STT-LLM-TTS 管线：三个专业模型串起来，默认走 LiveKit Inference（无需自备 API key）。Quickstart 里的默认组合是 AssemblyAI Universal-3.6 Pro（STT）+ Gemma 4 31B（LLM）+ Fish Audio S2.1 Pro（TTS）。
• 实时模型（realtime）：单个语音到语音模型，表达力与延迟更好，代价是可控性更差。默认示例是 OpenAI GPT Realtime 2.1。

适合谁：

• 要做语音助手、客服外呼、会议记录与实时多模态应用的团队；需要「能打断、能接电话、能上网页/App」的完整链路，而不是一个聊天框；
• 已经在用 LiveKit 做音视频、想把 AI 接进既有房间的开发者——这是它最顺的场景；
• 想先把原型跑起来、再决定自托管还是用云的人：同一套代码，Cloud 部署与自托管部署都支持。

不适合谁：

• 只想要「文本问答」的场景——用普通 LLM API 更省；
• 完全不想碰 WebRTC、也不想注册 LiveKit Cloud 的人：最短路径虽然是几条命令，但房间、token、参与者这套概念绕不过去；
• 对数据出境极度敏感、又不愿意自托管的团队（自托管可行，但要自己搭 LiveKit server 与模型 provider）。

与站内同类条目的关系：OmniVoice（本站 9.0）、Azure Speech（本站 8.5）、Qwen Audio Agent（本站 8.3）都是语音能力/服务层面的工具；LiveKit Agents 是框架，它可以把这些能力当成管线里的一个环节，而不是替代它们。

核验日期：2026-11-02。依据 官方文档站、Voice AI quickstart、LiveKit 定价页（Markdown 版）、GitHub 仓库 livekit/agents。

准备工作

• 运行时：Python ≥ 3.10（官方示例用 uv 管理），或 Node.js ≥ 20（用 pnpm，要求 ≥ 10.15.0）。二选一，不用都装。
• 一个 LiveKit Cloud 账号：免费档就能开始，官方 Quickstart 默认假设你在 Cloud 上有一个项目，用来拿 API key、做推理与媒体转发。
• LiveKit CLI：安装方式按平台来——macOS brew install livekit-cli，Linux curl -sSL https://get.livekit.io/cli | bash，Windows winget install LiveKit.LiveKitCLI。
• 一个麦克风和浏览器：跑通之后要在 Agent Console 里对着它说话，才算真的验证完。
• 时间预算：官方口径「less than 10 minutes」到「说上话」，前提是依赖装得顺；实际留 30 分钟更稳，主要时间花在 CLI 授权与依赖安装。

从零到「能对话」：五步

1. 装 CLI 并授权项目

lk cloud auth

这条命令会打开浏览器完成授权，把 Cloud 项目与本地 CLI 关联起来。没做这一步，后面的 lk agent init/dev/create 都会失败——它们都要读写项目资源。

2. 用模板初始化一个 Agent

lk agent init my-agent --template agent-starter-python
# 或 Node 版
lk agent init my-agent --template agent-starter-node

CLI 会把官方 starter 拉进 my-agent/ 目录，生成带凭据的 .env.local，并打印后续步骤。官方特别提醒：把它打印的聊天链接存下来——那是在浏览器里对 Agent 说话的控制台入口。

Starter 项目的价值不只是「能跑」：官方说它们包含可工作的 Agent、测试，以及一份为编码 Agent 优化的 AGENTS.md，让 Claude Code / Cursor 这类工具直接变成 LiveKit 专家。

3. 装依赖

cd my-agent
uv sync          # Python
# pnpm install   # Node

4. 本地跑起来

lk agent dev

dev 模式会把 Agent 连上 LiveKit，并让它从公网可达，方便你在 Agent Console 里直接说话测试。跑通后回到浏览器：打开项目 Agents 面板里的 Console 链接，点 Start a session，按麦克风说话。

5. 部署

lk agent create     # 注册并部署到 LiveKit Cloud
lk agent start      # 以生产模式启动

三种启动模式要分清：console（纯本地终端里对话）、dev（连云、可远程测试）、start（生产）。

成功判定

不要只看「终端没报错」，用这三条验收：

1. Console 里点 Start a session 后，你能听到 Agent 先开口打招呼（quickstart 代码里最后一句是 session.generate_reply(instructions="Greet the user and offer your assistance.")）；
2. 你说话时它有反应，中途打断它会停下（轮次检测生效）；
3. Console 的工具面板里能看到本轮的转写文本与会话指标（延迟、模型调用）。三条都成立，才算真的打通。

初级用法：三个可复制的改法

改法一：换模型。 官方 Quickstart 的 Agent 代码里，三段模型都写在 AgentSession(...) 里：

session = AgentSession(
    stt=inference.STT(model="assemblyai/universal-3-6-pro", language="en"),
    llm=inference.LLM(model="google/gemma-4-31b-it"),
    tts=inference.TTS(model="fishaudio/s2.1-pro", voice="fa4c9eb3dccc4806b382b40d61c6b10a"),
)

换 STT/LLM/TTS 就是改这几行；中文场景要把 language 换成 zh 并挑支持中文的 STT/TTS。想换实时模型，就整段换成 realtime 管线（默认示例是 OpenAI GPT Realtime 2.1）。

改法二：改人设。 Agent 子类的 instructions 就是系统提示。Quickstart 里的默认人设特意强调「不要用 emoji、星号等符号」——因为输出的文本会被 TTS 念出来，格式符号会变成噪音。这条经验值得照抄。

改法三：开降噪。 代码里 room_io.RoomOptions(audio_input=room_io.AudioInputOptions(noise_cancellation=...)) 配的是 ai-coustics 的增强模型（示例用 QUAIL_VF_S）。真机测试时如果识别率不稳，先怀疑环境噪音，再怀疑模型。

高级玩法

玩法一：一句话装好「编码 Agent 的 LiveKit 知识」。 在项目目录跑 lk skills install（加 --global 则对所有项目生效），它会同时装 Agent Skills 与 Docs MCP server，让 Claude Code / Cursor / Codex 直接具备 LiveKit 的领域知识。团队里多人开发时，这比每人各自喂文档省事。

玩法二：把测试当工程做。 文档有「Test & Evaluate」整块：可以给 Agent 加行为测试、用 CLI 的 agent debugger 试改动、在 Console 里看每轮的表现指标。上线前至少跑一遍行为测试，比人工点几十次靠谱。

玩法三：接电话。 文档有 Telephony 专区，配合 LiveKit 的 SIP 集成可以让 Agent 打电话/接电话。Cloud 的 Build 档还带 1 个免费号码，适合先验证外呼流程再谈扩容。

玩法四：自托管换掉云依赖。 想自己控数据：用开源 LiveKit server 自托管，代码侧做两处调整——去掉增强降噪插件，把模型换成自有 provider 的插件。官方写明这条路可行，代价是媒体与推理都得自己运维。

玩法五：用 Agent Builder 先验证产品形态。 不想写代码时，Agent Builder 可以在浏览器里搭一个原型，先跟产品/业务确认「这个语音助手到底要干什么」，再决定是否投入工程实现。官方自己也说它「功能不如 SDK 全」。

常见踩坑

踩坑 1：lk agent init 报找不到项目。 症状：命令提示需要选择项目，或直接失败。 原因：CLI 没有默认项目，或 lk cloud auth 没完成。 解决：先跑 lk cloud auth 完成浏览器授权，再重跑 init；多项目环境下确认选的是你要用的那个。

踩坑 2：终端里对着 Agent 说话没反应。 症状：lk agent dev 在跑，但你说话它不动。 原因：dev 模式是把 Agent 连到云上，需要从 Console 里发起会话——本地终端不等于会话通道。 解决：用 CLI 打印的 Console 链接（或项目 Agents 面板）点 Start a session；要用纯本地通道就换成 console 模式。

踩坑 3：Agent 回答里带一堆符号，TTS 念得很怪。 症状：听到「星号星号」「括号链接」之类的朗读。 原因：LLM 默认爱用 Markdown；语音场景里这些符号是噪音。 解决：在 instructions 里明确禁止 emoji、星号、链接等格式（官方 quickstart 的人设已经这么写），必要时在 TTS 前加一层文本清洗。

踩坑 4：中文识别很差。 症状：转写内容大段错乱。 原因：quickstart 默认 language="en"，且默认 STT 模型对中文的支持另说。 解决：把 language 改成 zh，并从 STT 模型列表里挑明确支持中文的；同时检查降噪是否开启（环境噪音对中文识别影响更大）。

踩坑 5：自托管部署后，云上的降噪/推理不可用。 症状：照 quickstart 代码跑了，但自托管环境里报插件或推理错误。 原因：增强降噪依赖 LiveKit Cloud 能力；inference.* 也是 Cloud 侧的推理通道。 解决：按官方文档的自托管章节，去掉增强降噪插件，把 STT/LLM/TTS 换成自有 provider 的插件实例。

踩坑 6：以为「部署成功」就等于「线上能用」。 症状：lk agent create 成功，但真实用户连不上或延迟很高。 原因：部署、并发、区域与网络都是独立变量；Build 档只有 5 个并发会话。 解决：部署后在 Console 里实测一轮，记录首字延迟与打断表现；并发预期超过 5 时要先看档位与定价，别等上线才发现。

踩坑 7：Node 侧 pnpm 版本太低，装依赖直接失败。 症状：pnpm install 报错或 peer 依赖解析异常。 原因：官方要求 pnpm ≥ 10.15.0。 解决：升级 pnpm 再装；Python 侧同理，确认 ≥ 3.10（用 uv 管理最省事）。

小技巧

• 先跑通 console 模式再上 dev：本地闭环能排除掉大部分「到底是模型问题还是网络问题」的纠结。
• 人设里写「回答要短、不要格式符号」：语音场景下，短句比信息量更重要。
• 打断行为要专门测：连续说三句话打断它，看它是否能立刻停——这是语音体验的分水岭。
• 把 agentName 记住（quickstart 里是 my-agent）：Console 里发起会话需要它。
• 换模型一次只换一个环节：STT、LLM、TTS 同时换，出了问题无法归因。
• 开发期多用行为测试，别只靠人手点：语音交互的回归成本比文本高得多。
• 成本按「会话分钟 + 模型推理」两条线算，Cloud 各档的包含额度不一样，先算清楚再选档。

常见问题 FAQ

Q1: LiveKit Agents 和 Pipecat、Vapi、Retell 这类方案有什么区别？

A: 定位不同。Vapi、Retell 是托管产品，配置化为主、开箱即用；Pipecat 与 LiveKit Agents 都是开源框架，代码掌控更强。LiveKit Agents 的差异在于它长在 LiveKit 的 WebRTC 基建上——房间、轨道、SIP 电话、录制这些是同一套体系，做「多人 + 实时 + 能接电话」的场景更顺；单独做一个语音聊天机器人则各家差别不大。

Q2: 必须用 LiveKit Cloud 吗？能完全自托管吗？

A: 能自托管，官方文档有明确路径：自托管开源 LiveKit server，生产环境用自定义部署，并做两处调整（去掉增强降噪插件、把模型换成自有 provider 插件）。代价是媒体链路与模型推理都要自己运维。Cloud 的好处是托管部署、可观测、推理免 key。

Q3: 免费额度够做什么？

A: 按官方定价页（采集日期 2026-11-02），Build 档 $0/月包含 1,000 分钟 Agent 会话、5 个并发会话、1 个 Agent 部署、1 个免费电话号码与推理额度，并带 Agent 可观测与会话指标。做原型和内部测试够用；上了真实用户再考虑 Ship（$50/月起，5,000 分钟含，超出 $0.01/分钟，20 并发）。

Q4: 支持中文吗？

A: 框架本身不限语言，取决于你选的 STT/TTS/LLM 是否支持中文，以及在 session 里声明的 language。默认 quickstart 是英文（AssemblyAI + Gemma + Fish Audio 组合，language="en"），中文场景要显式换模型与语言参数。

Q5: 一定要 WebRTC 知识吗？

A: 做 Hello World 不需要：lk agent init + lk agent dev 就够了。但要排查延迟、回声、丢包、并发这些问题，就得理解房间、参与者、轨道这些概念。官方的 WebRTC Transport 专区是补这块的地方。

Q6: 能做「打电话」吗？

A: 能。文档有 Telephony 专区，配合 SIP 集成可外呼/接听；Cloud 的 Build 档自带 1 个免费号码用于验证。生产外呼还要考虑合规与号码资源，那部分不在框架范围内。

进阶学习建议

把 LiveKit Agents 用出差别，靠的是对「轮次」与「管线」的理解，不是堆功能：

1. 精读 Turn detection & interruptions 与 Pipeline nodes & hooks 两页：前者决定「什么时候该说」，后者决定「说的每一段能插什么逻辑」。语音体验的绝大部分问题都落在这两处。
2. 用 agent-starter-python 的测试当模板：starter 自带测试骨架，先照它的结构给自己的 Agent 写行为测试，再谈加功能。
3. 对照 inference.* 模型清单做选型表：STT/LLM/TTS 各挑两个候选，按「中文支持、延迟、单价、可控性」四项打分，别凭感觉换。
4. 读 Agents & handoffs 与 Tasks & task groups：多 Agent 协作与任务分解在语音场景里对应「转人工」「多步骤表单」这类真实需求，值得单独做一次练习。
5. 拉一遍自托管文档：即使暂时用 Cloud，也要知道哪些能力是云侧的（增强降噪、Inference），否则迁移时会被隐形依赖绊住。
6. 看 Recipes 里的成品：官方的 examples/recipes 集合是「已经踩过坑的写法」，比自己从零设计会话流更快。

参考链接

• LiveKit Agents 文档首页
• Voice AI quickstart
• GitHub 仓库 livekit/agents
• LiveKit 定价页
• LiveKit CLI 文档
• Python starter 模板
• Node.js starter 模板

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。