debugging-livekit-agents

实时调试 LiveKit Agent

lk agent debugger 会在本地将用户的 Agent 作为后台进程运行，让你每次推动对话一轮。它专为编码 Agent 打造：你扮演用户，根据上一条回复选择下一句，并检查 Agent 在两轮之间做了什么。

默认情况下，会话采用文本模式：语音处于关闭状态，内容也不会发送到 LiveKit 房间，因此每轮都很快。如果问题出在音频链路上，请改用音频模式启动会话（参见音频模式）。

首次使用前，请确认此命令存在并阅读其帮助信息：

lk agent debugger --help

帮助信息十分详尽，是子命令和标志的准确信息来源，因此本文不会重复说明。如果找不到此命令，说明已安装的 CLI 版本太旧。请告知用户更新 lk，并在此之前使用 testing-livekit-agents。不要猜测旧版命令的用法。

调试循环

启动 Agent，发送用户轮次，检查发生的情况，编辑代码，重启，然后重复这些步骤，完成后停止。大致如下：

lk agent debugger start
lk agent debugger say "Hi, what can you do?"
lk agent debugger say "Book me a table for two tonight"
lk agent debugger stop

每次 say 都会打印 Agent 作出的所有响应（工具调用及其参数和结果、交接、错误），然后显示回复。在轮次之间，你可以查看 Agent 的聊天记录、实时事件流、进程日志和状态；子命令列表见 --help。

每次编辑代码后都要重启。 正在运行的会话会继续使用旧代码，很容易把时间浪费在调试文件中已不存在的行为上。

使用此工具进行调试

• 不仅要看回复，也要看工具调用。 回复会显示哪里出了问题；工具调用及其参数通常能说明原因。参数错误可能源于提示词或工具描述。完全没有调用，通常说明工具描述没有说明何时应使用该工具。
• 工具行为异常时，交错查看日志。 某个选项会在相应轮次下方显示 Agent 的日志行，因此工具的回溯信息会紧接在用户听到的已净化错误消息下方显示。这是从症状追查原因最快的方式。
• 查看 Agent 的聊天记录，不要只依赖对对话的记忆。 记录中包含 LLM 看到的内容，包括交接过程中指令和工具的变化。行为看似不可能时，聊天记录通常会显示上下文与你的假设并不一致。
• 修复前先复现，然后重新运行相同轮次。 保留触发错误的 say 语句序列，以便比较修复前后的情况。
• 推动完整对话。 大多数错误要经过多个轮次才会显现：早期收集的细节后来丢失、用户在流程中途改变想法，或交接时上下文丢失。单独一轮无法发现这些问题。
• 如果由程序决定轮次，就编写脚本。 此工具提供机器可读的输出和有意义的退出代码。请查看 --help 了解当前格式，不要假定字段名称。

音频模式

文本模式会跳过 STT 和 TTS，因此无法呈现以下情况：听到的名称被识别成另一种拼写、STT 将数字识别为单词、轮次过早结束，或任何仅接受音频的实时模型的情况。如果 CLI 支持此功能，使用音频启动会话（查看 start --help）后，每条 say 都会通过 LiveKit Inference TTS 播放到 Agent 的麦克风输入中，Agent 也会运行完整的音频处理流程。

• 当问题与听觉有关时使用此模式，或者 Agent 使用无法在文本模式下运行的语音转语音模型时使用。对于逻辑、提示词和工具问题，请继续使用文本模式：速度更快，而且转录噪声只会造成干扰。
• 需要 LiveKit Cloud 项目。 语音轮次通过 LiveKit Inference 运行，因此 lk 必须具有项目凭据。文本模式不需要凭据。
• 比较听到的内容与发送的内容。 每个轮次都会显示 Agent 对你所说内容的转录；如果文字不同，也会显示发送的文本。这种差异往往就是整个问题所在：Agent 对它听到的内容作出了正确回答。
• 按照来电者的说话方式编写内容。 测试 Agent 如何处理语音输入时，请将数字和代码写成单词；如果 Agent 应该接受这两种形式，请都进行测试。
• 模式属于会话。 重启会保留该模式；停止后重新启动即可切换模式。
• 长时间静默可能会导致轮次过早结束。 Agent 回答后保持安静一会儿，轮次就会结束。如果 Agent 在完成回答前暂停很久（例如，实时模型正在等待委派的回答），其余回复会显示在下一个轮次中。确认 Agent 没有回答之前，请先检查聊天记录。

音频模式仍然无法在 Agent 回复过程中打断它，也无法让你听到 Agent 的声音。对于这些情况，请使用 lk agent console 或音频模拟。

何时使用其他工具

情况	使用
你想听听效果，或者想给用户一些内容让他们试用	lk agent console（麦克风和扬声器，由真人操作键盘）
相同故障反复出现	轮次级回归测试（testing-livekit-agents）
需要大规模评估整段对话的结果	模拟（running-livekit-simulations）
需要检查某个轮次的转录或端点检测	音频模式下的调试器（见上文）
需要检查跨多段对话的打断情况或语音行为	音频模拟（running-livekit-simulations）

调试器用于交互式查找错误。找到错误后，请为它编写测试，以免后续更改在不知情的情况下再次引入该错误。

相关技能

• 构建 Agent：building-livekit-agents
• 将发现的错误固定为测试：testing-livekit-agents
• 整段对话检查：writing-livekit-scenarios、running-livekit-simulations
• 仅在生产环境中出现的故障（工作进程、提供商、关闭）：operating-livekit-agents
• CLI 标志和 API 事实：reading-livekit-docs