building-livekit-agents

构建 LiveKit Agent

本技能介绍如何构建语音 Agent。本文不涉及 API 细节，因为这些细节会变动； 请从 reading-livekit-docs 中查找。

本文假设使用 LiveKit Cloud，这是推荐的方案：使用托管基础设施，并使用模型的 LiveKit Inference， 这样就不必管理各个提供商的 API 密钥。

Agent 的运行位置与项目使用哪种 LiveKit 是两个不同的问题。用户可自托管的 Agent （运行在用户自己的服务器上，而非 LiveKit Cloud 的 Agent 托管服务上）仍会连接到 LiveKit Cloud，也仍可使用 LiveKit Inference。Inference 是 LiveKit Cloud 的一项功能，因此只有项目运行在 LiveKit OSS 上时才无法使用。无论采用哪种方案，架构建议都适用；在 LiveKit OSS 上，模型来自各个提供商自己的插件和 API 密钥。

编写代码之前

1. 加载 reading-livekit-docs，查找即将使用的 API。不要凭记忆编写 LiveKit 代码。
2. 确认项目已连接到 LiveKit Cloud 项目（或 LiveKit OSS 服务）： LIVEKIT_URL、LIVEKIT_API_KEY、LIVEKIT_API_SECRET，通常位于 .env 中。CLI 可以设置这些 配置。
3. 在编写第一个 Agent 类之前，确定工作流结构（见下文“结构”）。 事后再把单体拆分成多个 Agent，远比一开始就使用两个 Agent 更费力。
4. 规划验证方式。 现在就决定使用 debugging-livekit-agents（进行真实对话）、testing-livekit-agents（断言对话轮次），还是两者都用，因为这会影响代码的组织方式。

语音带来的要求变化

语音 Agent 不只是加了个扬声器的聊天 Agent。大多数设计决策都受以下限制影响：

延迟。 用户期望在几百毫秒内得到回复。上下文大小、工具数量、工具调用是否处于关键路径，以及响应是否以流式方式传输，都会占用或节省这部分时间预算。也要为网络卡顿和提供商超时做好准备；这些情况经常发生。

上下文大小。 任何模型处理包含 50 个工具定义的 10,000-token 系统提示词时都会感觉迟缓，因为模型每轮都会重新读取全部内容。每个阶段只提供它能调用的工具和所需指令。

聆听。 用户无法略读内容或回看前文，而且他们会打断 Agent。回复过长是个问题，沉默听起来像出了故障，而被打断是常态。

结构：交接与任务

常见的问题是让一个 Agent 处理所有事情。它会不断收集工具、指令和状态，直到变得迟缓且不可靠；到那时再拆分，就相当于重写。

交接会将控制权从一个 Agent 转交给另一个 Agent。应在自然的对话边界进行交接，例如从问候 → 信息收集 → 问题解决，或从一般支持 → 账单专员。这样，每个 Agent 只需携带自己的工具和指令。选择一个可以为下一个 Agent 总结上下文的边界。如果下一个 Agent 需要前一个 Agent 拥有的全部内容，说明边界划分不当。

任务是目标明确、范围有限的提示词，专注于一个结果。可将其用于不需要完整 Agent 的独立操作，或适合使用专门提示词而非通用提示词的场景。

如果无法用一句话说明某个 Agent 负责什么，就把它拆分。

工具

• 工具描述决定行为。 当 Agent 调用了错误的工具，或在错误的时机调用工具时，先检查描述，再归咎于模型。最常见的原因是描述没有说明何时使用该工具。
• 尽可能避免让工具处于关键路径上。 用户等待每次工具调用时，都会感受到延迟。
• 为工具故障做好准备。 确定后端宕机或未返回结果时 Agent 应该说什么。工具失败时会编造答案的 Agent，之后很难发现问题。

模型负责理解；代码负责状态

模型会读取对话并提出操作。应用代码负责管理记录、权限检查、状态转换和所有外部影响。大多数“演示中能用、生产环境中失效”的 Agent，都是在某处模糊了这条界限。

• 绝不要用代码判断意图。 批准、拒绝、更正、取消、“下周二”——这些都由运行时模型理解。正则表达式、关键词列表或短语白名单总会在你从未测试过的情况下出错；再加一道“保守”的检查门也有同样的问题。用代码验证结构（类型化日期、枚举、必填字段）；把含义留给模型。
• 工具调用代表模型的理解，并不能证明它理解正确。 将消息来源、版本检查、顺序和业务规则留在代码中，以便进行检查。
• 工具返回事实，而不是句子。 返回精简的数据、结果和可执行的错误信息；由模型决定措辞。只有在任务要求逐字披露时，才通过脚本指定确切文本。
• 跟随用户，而不是表单。 接受调用者主动提供的事实，只询问缺失或有歧义的信息；用户已明确回答后，绝不要再要求他们按固定话术表态（“说是以确认”）。
• 每个会话只使用一个权威状态对象，并将模型提供的事实与可信身份、时钟、ID 和回执分开。

让每项更改的含义都精确无误

代价最高的 Agent 错误，是变更超出或未达到调用者的本意：“别给他留备注”清空了整个列表；一项更正同时重置了已确认字段；重新陈述一个值却使批准失效。编写会修改状态的工具之前，先说明它的目标、会更改什么以及必须保持什么不变；然后将其与最接近的、必须执行不同操作的请求配对测试。

简要规则：省略意味着保留；缺失、空、未知和已清除是四种不同状态；集合中的条目使用由应用生成的 ID；先验证再应用；带范围限定的否定绝不清空整个集合；值未改变时不执行操作。如果任务要求在产生影响前进行审核，那么批准必须是针对该版本的后续真实用户消息；在语音边界跟踪交付情况；只有写入提交后才能发布成功结果。完整说明——包括结束流程、输出归属，以及文本和音频输入如何走不同的钩子路径——见 references/state-and-effects.md。在构建任何预订、编辑、确认或结束通话的功能之前，请先阅读。

从一个失败的完整路径测试开始

在扩展工具范围或打磨角色设定之前，选取一个普通的用户目标，让它经过真实 Agent 并实现所需效果——完成预订、更改记录或结束通话。根据用户的请求编写预期结果，而不是根据应用自身的导出内容编写。然后将其与第一个必须拒绝请求的防护条件配对，因为一个拒绝所有内容的测试无法证明防护有效。添加其他内容时，确保这组测试始终通过。

完成前进行验证

提示词更改和代码更改一样容易破坏 Agent 行为；手动试一次不算验证。

• 构建期间，使用 debugging-livekit-agents 进行对话测试。它会在本地运行 Agent，允许你通过文本或语音发送轮次，并展示每条回复背后的工具调用。
• 完成前，使用 testing-livekit-agents 编写测试。至少覆盖用户要求的核心行为、参数正确的工具调用（如果存在工具），以及一条失败路径。
• 发布到线上 Agent 之前，使用 writing-livekit-scenarios 和 running-livekit-simulations 运行模拟。

如果用户要求不编写测试，就不带测试进行构建；只需说明一次，你建议在投入生产前补上测试，然后继续。

常见错误

• “先”只用一个 Agent。 你是在预先决定结构；实现仍然可以很简单。
• 把延迟问题留到以后处理。 延迟会不断累积，而且越晚修复，成本越高。
• 照搬自己不理解的示例。 示例展示的是一种模式。整段照搬会带来你无法解释的额外上下文和组件。
• 认为自己掌握的模型知识是最新的。 事实并非如此。请参阅 reading-livekit-docs。
• 只靠手动测试就发布。 修改提示词会改变行为，却不会出现任何明显错误；测试能让你在用户发现之前发现问题。

相关技能

• 事实、API、更新日志：reading-livekit-docs
• 构建时驱动实时对话：debugging-livekit-agents
• 轮次级测试：testing-livekit-agents
• 整段对话测试：writing-livekit-scenarios、running-livekit-simulations
• 状态、审批、提交、交付、收尾：references/state-and-effects.md
• 部署并确保其在生产环境中保持健康：operating-livekit-agents