livekit-skills

LiveKit 语音 Agent 开发

本技能提供使用 LiveKit Agents SDK 构建语音 AI Agent 的指导，涵盖 LiveKit Cloud 和可自托管部署，并使用 lk CLI 访问文档和管理项目。所有有关 API、方法和配置的事实信息都必须来自实时文档。

强制要求：开始前阅读此检查清单

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

1. 阅读整个技能文档——不要跳过任何章节
2. 设置 LiveKit 凭据（Cloud 项目或可自托管服务）——你需要 LIVEKIT_URL、LIVEKIT_API_KEY 和 LIVEKIT_API_SECRET
3. 设置文档访问——安装 lk CLI，以使用 lk docs 命令
4. 计划编写测试——每个 Agent 实现都必须包含测试（参见下方的测试章节）
5. 根据实时文档验证所有 API——切勿依赖模型记忆中的 LiveKit API 信息

设置

LiveKit Cloud

LiveKit Cloud 是让语音 Agent 快速运行起来的最快方式。它提供：

• 托管基础设施（无需部署服务器）
• 用于 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 Cloud 时，LiveKit Inference 是访问 AI 模型的一种方式。它可让你通过 LiveKit 凭据访问领先的 AI 模型提供商，无需单独的 API 密钥。

LiveKit Inference 的优势：

• 无需为每个 AI 提供商分别管理 API 密钥
• 费用统一通过 LiveKit Cloud 账户结算
• 针对语音 AI 工作负载进行了优化

请查阅文档，了解可用模型、支持的提供商和当前使用方式。文档始终包含最新信息。

可自托管设置

可自托管部署不受 Cloud 套餐对部署数量和并发量的限制。你可以直接控制扩缩容。

本地开发

安装并运行 LiveKit 服务：

• macOS：brew install livekit
• Linux：curl -sSL https://get.livekit.io | bash

以开发模式启动：

livekit-server --dev

默认凭据：API 密钥 devkey，API 密钥 secret。

设置环境变量：

LIVEKIT_URL=ws://localhost:7880
LIVEKIT_API_KEY=devkey
LIVEKIT_API_SECRET=secret

生产环境部署

可通过 Docker、Kubernetes 或任意提供商（Hetzner、AWS、GCP 等）的虚拟机部署 livekit-server。详情请查阅 lk docs get-page /home/self-hosting 或参见 references/self-hosting.md。Agent 服务作为常规进程运行，由你的基础设施工具管理。

使用自己的模型提供商

进行可自托管部署，或希望使用自己的 API 密钥而非 LiveKit Inference 时，可通过环境变量直接配置模型提供商：

# STT (Speech-to-Text)
DEEPGRAM_API_KEY=your-key

# LLM
OPENAI_API_KEY=your-key

# TTS (Text-to-Speech)
ELEVEN_API_KEY=your-key
# or
CARTESIA_API_KEY=your-key

Agents SDK 为所有主要提供商提供插件。直接传入模型标识符：

Node.js / TypeScript：

import { voice } from "@livekit/agents";

const session = new voice.AgentSession({
  stt: "deepgram/nova-3:multi",
  llm: "openai/gpt-4.1-mini",
  tts: "cartesia/sonic-3:voice-id",  // or "elevenlabs/..."
});

Python：

session = AgentSession(
    stt="deepgram/nova-3",
    llm="openai/gpt-4.1-mini",
    tts="elevenlabs/...",  # or "cartesia/sonic-3:voice-id"
)

请查阅 lk docs search "plugins"，获取支持的提供商完整列表。

项目模板

使用 CLI 初始化新的 Agent 项目：

后端 Agent：

lk agent init my-agent --template agent-starter-python
lk agent init my-agent --template agent-starter-node

前端应用（React/Next.js、React Native、Swift、Flutter、Android）：

lk agent init my-frontend --template agent-starter-react
lk agent init my-frontend --template agent-starter-react-native

省略 --template，即可通过交互方式查看所有可用模板。

关键规则：切勿依赖模型记忆获取 LiveKit API 信息

LiveKit Agents 是一个快速演进的 SDK。模型训练数据在生成的那一刻就已经过时。使用 LiveKit 时：

• 切勿假设 API 签名、方法名称或配置选项
• 切勿猜测 SDK 行为或默认值
• 务必查阅最新文档进行核实，然后再编写代码
• 实现功能时务必引用文档来源

即使你确信自己了解某个 API，也必须遵守此规则。仍需核实。

使用 LiveKit CLI 查阅文档

编写任何 LiveKit 代码之前，请使用 lk docs CLI 命令获取最新且经过核实的 API 信息。这可以避免依赖过时的模型知识。

搜索文档

lk docs search "voice agent quickstart"
lk docs search "handoffs and tasks"

获取特定页面

lk docs get-page /agents/start/voice-ai-quickstart
lk docs get-page /agents/build/tools /agents/build/vision

搜索 SDK 源代码

lk docs code-search "class AgentSession" --repo livekit/agents
lk docs code-search "@function_tool" --language Python --full-file

查看更新日志

lk docs changelog livekit/agents
lk docs changelog pypi:livekit-agents --releases 5
lk docs changelog npm:livekit-agents --releases 5

如果未安装 CLI

请先安装 LiveKit CLI：

• macOS：brew install livekit-cli
• Linux：curl -sSL https://get.livekit.io/cli | bash
• Windows：winget install LiveKit.LiveKitCLI

也可将此技能附带的 references/ 目录中的参考页面用作备用资料。

语音 Agent 架构原则

语音 AI Agent 的需求与文本 Agent 或传统软件有着根本区别。请牢记以下原则：

延迟至关重要

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

• 尽量缩小大模型上下文，以降低推理耗时
• 对话进行期间，避免不必要的工具调用
• 优先采用流式响应，而非批量响应
• 为不理想的情况做好设计（网络延迟、API 超时）

上下文膨胀会损害性能

大型系统提示词和冗长的工具列表会直接增加延迟。无论模型速度多快，拥有 50 个工具和 10,000 个令牌系统提示词的语音 Agent 都会显得迟缓。

设计 Agent 时，应尽量精简上下文：

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

用户不会阅读，而是倾听

语音界面的限制与文本不同：

• 冗长的响应会让用户感到沮丧——输出应简洁
• 用户无法回看——确保首次传达时清晰明了
• 打断很常见——设计时应能妥善处理
• 沉默会让人觉得出了问题——必要时告知用户正在处理

工作流架构：交接与任务

复杂的语音 Agent 不应采用单体架构。LiveKit Agents 支持结构化工作流，既能保持低延迟，又能处理复杂用例。

单体 Agent 的问题

由单个 Agent 处理整个对话流程，会导致以下内容不断累积：

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

这会增加延迟并降低可靠性。

交接：Agent 间的转接

交接允许一个 Agent 将控制权转交给另一个 Agent。可使用交接来：

• 拆分不同的对话阶段（问候 → 信息收集 → 问题解决）
• 隔离专门能力（常规支持 → 账单专员）
• 管理上下文边界（每个 Agent 仅拥有所需内容）

请围绕自然的对话边界设计交接，在这些边界处可以概括上下文，而不必原样传递全部内容。

任务：限定范围的操作

任务是范围严格限定、旨在达成特定结果的提示词。可在以下情况使用任务：

• 无需完整 Agent 能力的独立操作
• 聚焦的提示词比通用 Agent 效果更好的情况
• 仅需特定能力时缩减上下文

有关交接和任务的实现细节，请查阅文档。

必须：为 Agent 行为编写测试

语音 Agent 的行为由代码决定。每个 Agent 实现都必须包含测试。交付没有测试的 Agent，就等于交付未经测试的代码。

强制测试工作流

构建或修改 LiveKit Agent 时：

1. 创建 tests/ 目录（如果尚不存在）
2. 至少编写一个测试，然后再认为实现已完成
3. 测试用户要求的核心行为
4. 运行测试，确认测试通过

测试驱动开发流程

修改 Agent 行为（指令、工具描述、工作流）时，请先为期望的行为编写测试：

1. 定义 Agent 在特定场景下应执行的操作
2. 编写用于验证该行为的测试用例
3. 实现功能
4. 反复迭代，直到测试通过

这种方法可以避免交付那些“看起来能用”、但在生产环境中失效的 Agent。

每项 Agent 测试都应涵盖的内容

至少应编写以下测试：

• 基本对话流程：Agent 能否恰当地回应问候
• 工具调用（如果存在工具）：工具是否使用正确的参数调用
• 错误处理：Agent 能否妥善处理意外输入

测试重点：

• 工具调用：Agent 是否调用了正确的工具，并使用正确的参数？
• 响应质量：Agent 是否针对给定输入生成恰当的响应？
• 工作流转换：交接和任务是否能正确触发？
• 边缘情况：Agent 如何处理意外输入、中断和静默？

测试实现模式

使用 LiveKit 的测试框架。通过 lk docs 查阅测试文档，了解当前的模式：

search: "livekit agents testing"

该框架支持：

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

为什么这是不可妥协的要求

在手动测试中“看起来能用”的 Agent，在生产环境中经常会失败：

• 提示词更改会在无提示的情况下破坏行为
• 工具描述会影响工具的调用时机
• 模型更新会改变响应模式

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

跳过测试

如果用户明确要求不编写测试，可以不编写，但请告知他们：

“我已按要求构建了不含测试的 Agent。我强烈建议在部署到生产环境之前添加测试。语音 Agent 很难通过手动方式验证，而测试可以防止行为在无提示的情况下退化。”

应避免的常见错误

让初始 Agent 承担过多职责

一开始就构建一个“什么都做”的 Agent，然后逐渐添加工具和指令。相反，应预先设计好工作流结构，即使初始实现很简单。

等到延迟成为问题才处理

延迟问题会不断累积。在开发时感觉“有点慢”的 Agent，在真实网络环境下的生产环境中会变得无法使用。持续测量并优化延迟。

不理解示例就照搬

文档中的示例用于展示特定模式。不理解示例用途就照搬代码，会导致 Agent 臃肿且结构不佳。纳入每个组件之前，先弄清它的作用。

因为“这不过是提示词”而跳过测试

Agent 的行为由代码决定。提示词更改对行为的影响不亚于代码更改。应以与传统软件相同的严谨程度测试 Agent 行为。交付 Agent 实现时，绝不能不附带至少一个测试文件。

假设模型掌握的知识是最新的

再次强调这条关键规则：绝不要相信模型对 LiveKit API 的记忆。SDK 的演进速度快于模型训练周期。务必核实所有内容。

何时查阅文档

始终查阅文档，了解以下内容：

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

此技能提供以下方面的指导：

• 架构方案和设计原则
• 工作流结构决策
• 测试策略
• 需要避免的常见问题

这一区别很重要：此技能会告诉你构建语音 Agent 时应如何思考。文档则会告诉你如何实现具体功能。

反馈循环

通过 lk docs 查阅 LiveKit 文档时，请留意其中的遗漏、过时信息或令人困惑的内容。报告文档问题有助于改善整个生态系统，让所有开发者受益。

总结

使用 LiveKit Cloud 构建高效的语音 Agent，需要：

1. 以 LiveKit Cloud + LiveKit Inference 为基础——这是最快的生产部署路径
2. 对照实时文档核实所有信息——切勿相信模型的记忆
3. 在每个架构决策节点将延迟降至最低
4. 使用交接和任务构建工作流，以管理复杂性
5. 在更改前后测试行为——未经测试绝不发布
6. 尽量减少上下文——只包含当前阶段所需的内容

无论 SDK 版本或 API 如何变化，这些原则始终适用。所有实现细节都请通过 lk docs 查阅 LiveKit 文档。