operating-livekit-agents

运行 LiveKit Agent

Agent 运行后的一切：将版本部署到 LiveKit Cloud，在真实负载下保持快速且稳定运行，并在不影响现有运行实例的情况下进行更改。命令位于 lk agent 下；请阅读 lk agent --help 和各子命令的帮助，而不要依赖本文提供的标志——本文有意不重复列出这些内容。reading-livekit-docs 包含部署和可观测性文档。

部署到 LiveKit Cloud

即使标志会变化，整体流程也保持稳定：

1. 项目目录通过配置文件绑定到 Agent，该文件由 CLI 创建（livekit.toml）。从该目录运行命令时，无需指定 ID 即可找到 Agent。
2. Agent 以容器形式交付。 CLI 可以为项目生成 Dockerfile，也可以使用你提供的预构建镜像。首次部署前，请在本地运行容器的启动命令（lk agent start）——这是生产模式，采用生产日志记录并会在关闭时排空请求，与 dev 模式的运行方式不同。
3. 每次部署都会创建一个版本并将其发布。status、versions 和 logs（构建日志与部署日志是分开的）会告诉你当前运行的版本以及发布失败的原因。
4. 密钥以环境变量的形式注入，并与代码分开管理——绝不将其烘焙进镜像或提交到代码库。更改密钥会重启 Agent。
5. 回滚会恢复到先前的版本。 回滚速度取决于套餐；请以文档为准。务必提前了解回滚命令。

部署后，请使用与检查陌生 Agent 相同的工具进行验证：用 status 检查发布情况，用 logs 查看最初几分钟的日志，并进行一次真实对话——running-livekit-simulations 可以按名称对已部署的 Agent 运行场景文件，这是最经济的端到端检查，可确认实际处理流量的正是你计划发布的版本。

Worker 进程模型

两个 SDK 都会从父进程生成 Worker 进程来运行会话。误解这一点是生产环境独有错误最常见的来源。

父进程预热；子进程继承。 通过 SDK 的预热钩子在父进程中加载开销较大的只读资源——VAD 和轮次检测模型、持久化客户端等；这样每个会话都能继承这些资源，无需重新加载。以这种方式共享的所有内容都必须是只读的或具备并发安全性；从子进程修改父进程状态的行为未定义。不要预热特定会话的状态，也不要预热那些占用的内存超过其节省成本的内容——父进程中的每个字节都会计入每个子进程的内存占用。接着，确认子进程确实使用了预热实例：一个经典错误是预热了模型，却又在会话代码中加载了新模型，导致预热毫无作用，启动依然缓慢。

事件循环由框架管理。 切勿在 Worker 内创建新的异步运行时，也不要从同步构造函数中阻塞等待异步调用来强行获取结果。如果初始化需要异步操作，请在已有的异步方法中首次使用时再延迟加载，或者将构造与等待执行的 initialize 步骤分开。当你遇到事件绑定到不同循环、循环已在运行、任务在等待期间被销毁，或已关闭的循环无法重用等错误时，原因几乎总是上述两种情况之一——追溯异步运行时的创建位置，或同步路径等待了某项操作的位置。

提供方

STT、TTS、LLM、VAD 和任何后端在生产环境中都会发生故障：速率限制、超时、过载、中断。设置超时时间——一直卡住的调用比快速失败更糟。区分值得重试的暂时性故障和需要回退或升级处理的持续性故障。降级时要给出有意义的语音响应，绝不能陷入沉默。记录提供方的响应时间，因为延迟上升通常是服务中断的第一个迹象。

为现有 Agent 添加提供方时：先检查 SDK 是否已有插件，再考虑自行编写；遵循代码库为其他提供方初始化、配置和处理错误的现有方式；让其配置经过同一套处理流程；并在真实的延迟条件下进行测试，而不只是测试理想情况下的响应。

性能：先衡量，再做任何改动

用户感受到的指标是首段音频耗时——从呼叫者说完到 Agent 开始说话的时间。优化前先拆分这段耗时：连接、提供方初始化、首次推理、工具执行。关注长时间通话中的上下文增长；如果历史记录没有上限，每一轮都会比上一轮更慢。

值得用 grep 搜索的反模式：

• 在异步上下文中进行同步 I/O。 一次阻塞的 HTTP 调用或文件读取，就会冻结该进程中的所有并发操作的音频处理。
• 通话期间加载——在会话内首次使用时才加载模型或建立连接，呼叫者会直接感受到这段延迟。将其移到预热或会话设置阶段。
• 没有摘要的无上限上下文。
• 不论对话处于哪个阶段，都全局注册所有工具；每个定义都会增加每次 LLM 调用的成本。

端点检测和轮次检测都是需要调整的参数，不应默认照搬。设置过于激进，Agent 会抢在正在停顿思考的人前面说话；设置过于保守，每次回复都会显得迟缓。合适的设置取决于使用场景——处理复杂问题的客服 Agent 需要更有耐心，快速回答型助手则需要速度。使用音频模拟进行衡量（running-livekit-simulations 会评估轮流发言和感知延迟），不要凭感觉判断。

关闭与升级

在生产模式下，服务器收到终止信号后会排空任务：停止接收新任务，在排空超时时间内完成活动任务，然后退出。有两种情况会导致问题。编排器的宽限期短于排空超时时间，会导致通话说到一半就被终止——请让两者保持一致。与任务生命周期无关的通话后工作（写入状态、发布事件、完成录音）也会被中断——确保这些工作能在排空期间完成。开发模式不会排空任务，因此必须在启动模式下测试关闭行为。

SDK 迭代很快，跨版本变更可能造成破坏。固定版本。升级前，使用 reading-livekit-docs 阅读变更日志。在分支上升级，运行测试套件，然后进行真实对话并运行模拟测试套件——有些回归问题只会在实际对话中出现。部署后的最初几小时内，密切关注延迟和错误率。

可观测性

以下三点能让生产事故更容易排查，而不再是一团谜：

• 每条日志都包含会话 ID，这样就能端到端追踪一次通话。
• 为各阶段的边界计时——已连接、用户首次说话、Agent 首次响应——以便看出延迟是在哪个阶段出现的，而不只是知道出现了延迟。
• 单独跟踪提供方指标，不与应用日志混在一起，这样无需翻查日志也能发现提供方性能下降。

LiveKit Cloud 提供 Agent 日志、会话洞察和追踪数据，你可以将其导出到自己的可观测性提供方；文档介绍了可用内容以及如何接入。

调试生产故障

先分类，再复现：

• 循环和任务错误 — 上文所述的工作进程模型。查找创建运行时或同步路径等待的位置。
• 提供方超时与性能下降 — 单次超时是暂时性的；延迟趋势不断上升则说明存在系统性问题。提供方响应时间日志可以告诉你原因。
• 工具无声失败 — 工具抛出错误后被框架捕获，用户只听到含糊的回复，或什么也没听到。工具需要显式错误处理，返回模型可以转述的内容。
• 连接不稳定 — 在此基础上添加重试前，先了解 SDK 内置的重新连接机制；记录连接状态变化。

然后在本地处理：使用 debugging-livekit-agents 复现对话，使用 testing-livekit-agents 将原因固定为测试；如果是整个对话失败，则添加一个场景，避免它悄无声息地再次发生。

更改已上线的代码库

先阅读项目自身的文档和约定——它们优先于任何通用指南。在编写代码前，阅读两三个与你即将添加的模块类似的模块，并遵循它们的初始化、配置、测试方式，以及接入配置流水线的方式。使用现有的测试固件和模拟模式，而不是另建一套；对已有做法另辟蹊径，会让未来的每位贡献者都感到困惑。在边界处进行模拟——例如提供方调用、数据库；并测试真实的模块逻辑。

相关技能

• 从头设计 Agent：building-livekit-agents
• 在本地复现糟糕的对话：debugging-livekit-agents
• 将生产环境中的 Bug 固定为测试：testing-livekit-agents
• 针对已部署 Agent 进行端到端检查：running-livekit-simulations
• 部署和可观测性文档、变更日志：reading-livekit-docs