testing-livekit-agents

测试 LiveKit Agents

回合级测试是 Agent 能拥有的成本最低且持久有效的验证方式。它们在用户现有的测试套件中以文本模式运行，而且速度足够快，可以在每次提交时执行。框架的辅助函数名称和签名会发生变化，因此编写测试前，请使用 reading-livekit-docs 查阅；对于本指南未涵盖的所有 API 细节，请参阅测试文档页面。

每个测试的结构都相同：使用待测 Agent 启动测试会话，运行一个用户回合，并断言该回合产生的事件。

测试断言的内容

一个回合会产生一系列事件。简单的回合只有一条消息。更常见的情况是：一次工具调用、它的输出、可能发生的交接，然后是一条消息。编写测试时，按顺序遍历这一系列事件，对每个事件进行断言，最后断言回合没有其他内容。

断言分为三种，了解该使用哪一种是本指南的重点。

结构断言检查消息角色、是否调用了工具、工具参数、工具返回内容，以及是否交接给了特定 Agent。它们具有确定性，且失败原因明确，因此应优先使用。

评判断言使用 LLM 评判辅助函数，将一条消息和一个意图字符串交给模型，询问两者是否匹配。用于断言回复内容，因为无法对内容进行精确断言。描述意图时应说明结果（“告知用户预订已确认并给出时间”），而不是具体措辞。

整段对话断言使用评判组辅助函数，对完整聊天记录并发运行多个内置评判器，并汇总它们的判定结果。内置评判器覆盖依据充分性、相关性、安全性、任务完成情况和工具使用等维度；当前包含的评判器请见文档。当问题涉及多个回合时，使用这种断言。

经验法则：

• 先断言结构，只对剩余部分使用评判。 本可使用结构断言的内容若改用评判断言，速度会更慢，也更容易不稳定。
• 结束回合。 断言没有后续事件。否则，即使 Agent 还执行了你不希望它执行的操作，测试也可能通过。
• 每个测试只验证一种行为。 当一个测试断言六件事时，即使失败，也很难看出问题所在。

模拟工具

测试不应访问真实后端，因为这会导致测试套件变慢且结果不确定。为待测 Agent 覆盖工具，并返回固定值。

除了 API 之外，还需注意两点：

• 成功和失败都要模拟。 从模拟工具返回错误会使工具抛出异常，从而可以测试后端不可用时 Agent 会如何回复。大多数 Agent 都缺少这类测试，而用户最容易注意到的正是这种行为。
• 作用域很重要。 默认情况下，模拟在你自己的 run() 调用周围的代码块内生效，这正是测试所需的作用域。也有针对会话的作用域形式，适用于独立运行且整个生命周期都需要启用模拟的会话。模拟入口使用这种形式，测试则不使用。请参阅 writing-livekit-scenarios。

模拟只会改变执行过程。模型仍会看到真实的工具架构，因此工具选择仍在测试范围内。

多回合和预置历史记录

有两种方法可以测试依赖先前回合的行为：

• 运行这些回合。 每个回合都会添加到对话历史记录中，因此第二个回合能看到第一个回合。路径本身很重要时使用这种方式，例如跨回合收集详细信息、用户在流程中途改变主意，或交接时携带上下文。
• 预置历史记录。 构建聊天历史记录并将其提供给 Agent，使其从你关心的状态开始。当用于设置状态的回合并非测试重点时，使用这种方式。与重放五个回合以到达第六个回合相比，这种方式更快，也更不容易出问题。

测试什么

大致按价值排序：

1. 用户要求的行为。 每个 Agent 至少都需要测试这一点。
2. 工具调用：针对具有代表性的请求，调用正确的工具并传入正确的参数。
3. 工具失败：工具出错或未返回任何内容时，Agent 会怎么说。
4. 拒绝与限制：Agent 拒绝应当拒绝的请求，也不会编造自己无法获取的数据。拒绝就是通过条件。
5. 交接：应当触发时完成交接，并确保下一个 Agent 获得所需信息。
6. 修复过的每个 Bug。 不写测试，修复过的 Bug 就可能悄无声息地再次出现。

三类证据，分别看待

针对会执行操作的 Agent（预订、编辑、确认），测试套件需要三类测试。混淆它们，就会让有问题的 Agent 通过全部测试：

• 确定性应用测试直接针对应用核心，验证守卫逻辑、无操作、空值与未知值的区别、修正、存储失败和重试。速度快、结果精确，不涉及模型。
• 使用脚本化提供方的真实 SDK 测试验证事件连接和工具调用链路：监听器是否触发，工具是否收到会话发送的内容。脚本化提供方只能证明机制，不能证明语言理解——其中的精确句子是测试固定数据，不是要求。
• 使用真实模型的日常语言测试验证模型能否根据调用者实际说话的方式完成任务：提示词中没有的改述、与同意混在一起的修正，以及同一句简短回复对不同问题作答。

看起来像测试、其实不是的捷径：调用辅助函数或填充私有状态，而不是驱动交互；告诉测试调用者要指定哪个工具；模拟本该测试正确性的那项修改；只把输出与应用自身的导出结果比较；某轮失败后反复重试直到通过；删除失败的断言。

不要编写惩罚正确行为的测试

最常见的错误 Agent 测试，会断言 Agent 做出不该做的事：陈述它无法获知的数据、给出具体的医疗、法律或财务建议，或完成本应被阻止的流程。如果 Agent 只有做出不当行为才能通过，就应该修正测试。

对于防护措施，Agent 拒绝、升级处理或不编造内容，就是通过。应按这种方式编写断言。

本文档的位置

• 构建时进行交互式试探 → debugging-livekit-agents。反馈循环更快，不保留断言。
• 逐轮测试，确定性执行，每次提交都运行 → 本文档。这是成本最低的持久检查。
• 发布前由模拟用户评估完整对话 → running-livekit-simulations。成本更高，但能发现逐轮测试遗漏的涌现行为。

如果模拟总是以相同方式失败，问题通常出在逐轮测试层面。在这里为其编写测试，更精确地锁定原因，并更早发现问题。

相关技能

• 当前 API 表面：reading-livekit-docs
• 先定位 Bug：debugging-livekit-agents
• 模拟，包括种子状态和会话范围的模拟对象：writing-livekit-scenarios、running-livekit-simulations