mcpField
L
livekit-agents

livekit-agents

github.com/livekitAgent 工作流744.1k 次安装1 周前更新
代码仓库

关于 livekit-agents

livekit-agents 是面向 LiveKit Cloud 开发者的语音 AI Agent 开发技能，提供架构、测试和文档查证指导，而非 API 参考。

主要功能

  1. 01LiveKit Cloud 设置指导
  2. 02语音 Agent 架构原则
  3. 03交接与任务设计
  4. 04Agent 测试工作流
  5. 05实时文档查证

适用场景

  1. 01规划语音 Agent 工作流
  2. 02设计交接和范围明确的任务
  3. 03为 Agent 行为添加测试
  4. 04编码前核对 LiveKit API

MCP 相关

该技能要求在编写 LiveKit 代码前使用 LiveKit 文档 MCP 服务查询 API 和配置。若无法使用 MCP，则建议改用网页搜索，并将代码标记为未经验证。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/livekit/agent-skills --skill livekit-agents

安装后在 Claude Code 中输入/livekit-agents确认已加载。

附带文件references/freshness-rules.md

详细介绍

面向 LiveKit Cloud 的 LiveKit Agents 开发

本技能提供使用 LiveKit Cloud 构建语音 AI Agent 的指导方针。本文假设你使用的是 LiveKit Cloud（推荐方式），并侧重说明如何开展 Agent 开发，而非 API 细节。有关 API、方法和配置的所有事实信息都必须以实时文档为准。

本技能适用于 LiveKit Cloud 开发者。 如果你自行托管 LiveKit，部分建议（尤其是关于 LiveKit Inference 的建议）可能不直接适用。

必须：开始前阅读此检查清单

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

  1. 阅读本技能文档全文——即使 MCP 可用，也不要跳过任何部分
  2. 确保已连接 LiveKit Cloud 项目——你需要从 Cloud 项目获取 LIVEKIT_URL、LIVEKIT_API_KEY 和 LIVEKIT_API_SECRET
  3. 设置文档访问方式——如果 MCP 可用，请使用 MCP；否则使用网页搜索
  4. 计划编写测试——每个 Agent 实现都必须包含测试（见下文的测试部分）
  5. 根据实时文档核实所有 API——绝不要依赖模型对 LiveKit API 的记忆

无论 MCP 是否可用，都必须遵循此检查清单。MCP 可用于访问文档，但不能替代本技能中的指导。

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 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/

从该页面获取适用于用户所用编码 Agent 的安装说明。

MCP 不可用时的备用方案

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

  1. 立即告知用户，无法实时核实文档
  2. 使用网络搜索从 docs.livekit.io 获取最新文档
  3. 使用类似 # UNVERIFIED: Please check docs.livekit.io for current API 的注释，明确标记所有 LiveKit 专属代码
  4. 明确说明无法核实的内容：“我无法根据当前文档核实此 API 签名”
  5. 建议用户在使用代码前查阅 https://docs.livekit.io 进行核实

语音 Agent 架构原则

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

延迟至关重要

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

  • 尽量缩减大模型上下文，以减少推理时间
  • 对话进行期间避免不必要的工具调用
  • 优先选择流式响应，而非批量响应
  • 针对不理想情况进行设计（网络延迟、API 超时）
上下文膨胀会降低性能

较长的系统提示词和大量工具列表会直接增加延迟。无论模型速度如何，配备 50 个工具和 10,000 个 Token 系统提示词的语音 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 的测试框架。通过 MCP 查阅测试文档，了解当前的模式：

search: "livekit agents testing"

该框架支持：

  • 模拟用户输入
  • 验证 Agent 的回应
  • 断言工具调用
  • 测试工作流转换
为什么这是不可妥协的要求

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

  • 提示词变更会在不知不觉中破坏行为
  • 工具描述会影响工具的调用时机
  • 模型更新会改变回应模式

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

跳过测试

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

“我已按要求在未编写测试的情况下构建了 Agent。强烈建议在部署到生产环境之前补充测试。语音 Agent 很难通过手动方式验证，而测试可以防止不易察觉的回归问题。”

应避免的常见错误

让初始 Agent 承担过多职责

一开始就用一个“什么都做”的 Agent，之后再不断添加工具和指令。应当预先设计工作流结构，即使初始实现很简单也不例外。

等到延迟成为问题才着手处理

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

不求甚解地照搬示例

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

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

Agent 的行为也是代码。提示词变更对行为的影响不亚于代码变更。应像测试传统软件一样严谨地测试 Agent 行为。交付 Agent 实现时，绝不能没有至少一个测试文件。

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

重申这条关键规则：对于 LiveKit API，绝不要相信模型的记忆。SDK 的演进速度快于模型的训练周期。务必核实所有信息。

何时查阅文档

务必查阅以下内容的文档：

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

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

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

区分两者很重要：本技能告诉你构建语音 Agent 时应如何思考。文档则告诉你如何实现具体功能。

反馈循环

通过 MCP 使用 LiveKit 文档时，请留意其中的遗漏、过时信息或令人困惑的内容。报告文档问题有助于为所有开发者改进生态系统。

总结

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

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

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

评论

支持 Markdown