livekit-agents

LiveKit Cloud 的 LiveKit Agents 开发

本技能提供使用 LiveKit Cloud 构建语音 AI 代理的指导性建议。它假设您正在使用 LiveKit Cloud（推荐路径），并编码了如何进行代理开发，而非 API 细节。所有关于 API、方法和配置的事实信息必须来自实时文档。

本技能适用于 LiveKit Cloud 开发者。 如果您自行托管 LiveKit，某些建议（特别是关于 LiveKit Inference 的）可能不直接适用。

必读：开始前请检查清单

在编写任何代码之前，请完成此检查清单：

1. 阅读整个技能文档 - 即使 MCP 可用，也不要跳过任何部分
2. 确保 LiveKit Cloud 项目已连接 - 您需要来自 Cloud 项目的 LIVEKIT_URL、LIVEKIT_API_KEY 和 LIVEKIT_API_SECRET
3. 设置文档访问 - 如果可用，使用 MCP；否则使用网络搜索
4. 计划编写测试 - 每个代理实现必须包含测试（请参阅下面的测试部分）
5. 对照实时文档验证所有 API - 切勿依赖模型记忆来获取 LiveKit API

无论 MCP 是否可用，此检查清单均适用。MCP 提供文档访问，但不会取代本技能中的指导。

LiveKit Cloud 设置

LiveKit Cloud 是让语音代理运行的最快方式。它提供：

• 托管基础设施（无需部署服务器）
• 用于 AI 模型的 LiveKit Inference（无需单独的 API 密钥）
• 内置降噪、语音检测和其他语音功能
• 简单的凭据管理

连接到您的 Cloud 项目

1. 在 cloud.livekit.io 注册（如果尚未注册）

2. 创建一个项目（或使用现有项目）

3. 从项目设置中获取您的凭据：

   • LIVEKIT_URL - 您项目的 WebSocket URL（例如 wss://your-project.livekit.cloud）
   • LIVEKIT_API_KEY - 用于身份验证的 API 密钥
   • LIVEKIT_API_SECRET - 用于身份验证的 API 密钥

4. 将这些设置为环境变量（通常在 .env.local 中）：

LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=your-api-key
LIVEKIT_API_SECRET=your-api-secret

LiveKit CLI 可以自动设置凭据。请查阅 CLI 文档以获取当前命令。

使用 LiveKit Inference 处理 AI 模型

LiveKit Inference 是在 LiveKit Cloud 中使用 AI 模型的推荐方式。 它提供对领先 AI 模型提供商的访问——全部通过您的 LiveKit 凭据，无需单独的 API 密钥。

LiveKit Inference 的优势：

• 无需为每个 AI 提供商管理单独的 API 密钥
• 计费合并到您的 LiveKit Cloud 账户中
• 针对语音 AI 工作负载进行了优化

请查阅文档以获取可用模型、支持的提供商和当前使用模式。文档始终提供最新信息。

关键规则：切勿信任模型记忆中的 LiveKit API

LiveKit Agents 是一个快速发展的 SDK。模型训练数据在创建时就已经过时。使用 LiveKit 时：

• 切勿假设 API 签名、方法名称或配置选项来自记忆
• 切勿猜测 SDK 行为或默认值
• 始终对照实时文档进行验证，然后再编写代码
• 始终引用实现功能时的文档来源

即使对某个 API 很有信心，此规则也适用。无论如何都要验证。

必需：使用 LiveKit MCP 服务器获取文档

在编写任何 LiveKit 代码之前，请确保可以访问 LiveKit 文档 MCP 服务器。这提供当前、经过验证的 API 信息，并防止依赖过时的模型知识。

检查 MCP 可用性

查找 livekit-docs MCP 工具。如果可用，请将其用于所有文档查找：

• 在实现任何功能之前搜索文档
• 验证 API 签名和方法参数
• 查找配置选项及其有效值
• 为特定任务找到工作示例

如果 MCP 不可用

如果 LiveKit MCP 服务器未配置，请通知用户并建议安装。所有支持平台的安装说明可在以下位置获取：

https://docs.livekit.io/intro/mcp-server/

从该页面获取适合用户编码代理的安装说明。

MCP 不可用时的回退方案

如果无法在当前会话中安装 MCP：

1. 立即通知用户无法实时验证文档
2. 使用网络搜索从 docs.livekit.io 获取当前文档
3. 明确标记所有 LiveKit 特定代码，添加类似 # UNVERIFIED: Please check docs.livekit.io for current API 的注释
4. 明确说明何时无法验证某些内容：“我无法对照当前文档验证此 API 签名”
5. 建议用户在使用代码前对照 https://docs.livekit.io 进行验证

语音代理架构原则

语音 AI 代理与基于文本的代理或传统软件有根本不同的要求。请内化这些原则：

延迟至关重要

语音对话是实时的。用户期望在几百毫秒内得到响应，而不是几秒。每个架构决策都应考虑延迟影响：

• 最小化 LLM 上下文大小以减少推理时间
• 在活跃对话期间避免不必要的工具调用
• 优先使用流式响应而非批量响应
• 为不愉快路径（网络延迟、API 超时）进行设计

上下文膨胀会扼杀性能

大型系统提示和广泛的工具列表直接增加延迟。一个拥有 50 个工具和 10,000 个 token 系统提示的语音代理，无论模型速度如何，都会感觉迟钝。

设计具有最小可行上下文的代理：

• 仅包含与当前对话阶段相关的工具
• 保持系统提示集中且简洁
• 移除当前不需要的工具和上下文

用户不阅读，他们倾听

语音界面约束与文本不同：

• 长响应让用户沮丧——保持输出简洁
• 用户无法回滚——确保首次传达清晰
• 中断是正常的——设计优雅处理
• 沉默感觉像故障——在需要时确认处理

工作流架构：交接和任务

复杂的语音代理不应是单一的。LiveKit Agents 支持结构化工作流，在保持低延迟的同时处理复杂用例。

单一代理的问题

处理整个对话流程的单一代理会积累：

• 每个可能操作的工具（臃肿的工具列表）
• 每个对话阶段的指令（臃肿的上下文）
• 所有场景的状态管理（复杂性）

这会产生延迟并降低可靠性。

交接：代理到代理的转换

交接允许一个代理将控制权转移给另一个代理。使用交接来：

• 分离不同的对话阶段（问候 → 信息收集 → 解决）
• 隔离专业能力（一般支持 → 计费专家）
• 管理上下文边界（每个代理只有它需要的内容）

围绕自然对话边界设计交接，在这些边界处可以总结上下文，而不是整体转移。

任务：限定范围的操作

任务是紧密限定的提示，旨在实现特定结果。使用任务来处理：

• 不需要完整代理能力的离散操作
• 聚焦提示优于通用代理的情况
• 仅需要特定能力时减少上下文

请查阅文档以获取交接和任务的实现细节。

必需：为代理行为编写测试

语音代理行为是代码。每个代理实现必须包含测试。没有测试就发布代理相当于发布未经测试的代码。

强制测试工作流

在构建或修改 LiveKit 代理时：

1. 创建 tests/ 目录（如果不存在）
2. 在认为实现完成之前至少编写一个测试
3. 测试用户请求的核心行为
4. 运行测试以验证它们通过

测试驱动开发流程

在修改代理行为（指令、工具描述、工作流）时，首先为所需行为编写测试：

1. 定义代理在特定场景下应做什么
2. 编写验证此行为的测试用例
3. 实现功能
4. 迭代直到测试通过

这种方法可以防止发布“看似有效”但在生产环境中失败的代理。

每个代理测试应覆盖的内容

至少编写以下测试：

• 基本对话流程：代理对问候语做出适当响应
• 工具调用（如果存在工具）：使用正确参数调用工具
• 错误处理：代理优雅地处理意外输入

重点关注测试：

• 工具调用：代理是否使用正确参数调用正确的工具？
• 响应质量：代理是否对给定输入产生适当的响应？
• 工作流转换：交接和任务是否正确触发？
• 边缘情况：代理如何处理意外输入、中断、沉默？

测试实现模式

使用 LiveKit 的测试框架。通过 MCP 查阅测试文档以获取当前模式：

search: "livekit agents testing"

该框架支持：

• 模拟用户输入
• 验证代理响应
• 工具调用断言
• 工作流转换测试

为什么这是不可协商的

在手动测试中“看似有效”的代理经常在生产环境中失败：

• 提示更改会静默破坏行为
• 工具描述影响工具何时被调用
• 模型更新改变响应模式

测试在用户发现问题之前捕获这些问题。

跳过测试

如果用户明确要求不进行测试，则继续执行，但通知他们：

"我已按要求构建了没有测试的代理。我强烈建议在部署到生产环境之前添加测试。语音代理很难手动验证，测试可以防止静默回归。"

要避免的常见错误

初始代理过载

从一个“做所有事情”的代理开始，然后随时间添加工具/指令。相反，应提前设计工作流结构，即使初始实现很简单。

忽略延迟直到成为问题

延迟问题会累积。在开发中感觉“有点慢”的代理，在生产环境中面对真实网络条件会变得不可用。持续测量和优化延迟。

不理解就复制示例

文档中的示例演示了特定模式。在不理解其目的的情况下复制代码会导致臃肿、结构不良的代理。在包含每个组件之前理解其作用。

因为“只是提示”而跳过测试

代理行为是代码。提示更改对行为的影响与代码更改一样大。以与传统软件相同的严谨性测试代理行为。切勿在至少一个测试文件的情况下交付代理实现。

假设模型知识是最新的

重申关键规则：切勿信任模型记忆中的 LiveKit API。SDK 的发展速度快于模型训练周期。验证一切。

何时查阅文档

始终查阅文档以获取：

• API 方法签名和参数
• 配置选项及其有效值
• SDK 版本特定功能或更改
• 部署和基础设施设置
• 模型提供商集成细节
• CLI 命令和标志

本技能提供以下指导：

• 架构方法和设计原则
• 工作流结构决策
• 测试策略
• 要避免的常见陷阱

区别很重要：本技能告诉您如何思考构建语音代理。文档告诉您如何实现特定功能。

反馈循环

通过 MCP 使用 LiveKit 文档时，请注意任何空白、过时信息或令人困惑的内容。报告文档问题有助于改善所有开发者的生态系统。

总结

使用 LiveKit Cloud 构建有效的语音代理需要：

1. 使用 LiveKit Cloud + LiveKit Inference 作为基础——这是通往生产环境的最快路径
2. 对照实时文档验证一切——切勿信任模型记忆
3. 在每个架构决策点最小化延迟
4. 使用交接和任务结构化工作流以管理复杂性
5. 在更改前后测试行为——切勿在没有测试的情况下发布
6. 保持上下文最小化——仅包含当前阶段所需的内容

无论 SDK 版本或 API 更改如何，这些原则仍然有效。有关所有实现细节，请通过 MCP 查阅 LiveKit 文档。