Back to Details

debugging-livekit-agents

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Debugging a LiveKit agent live

实时调试LiveKit agent

lk agent debugger
runs the user's agent locally as a background process in text mode and lets you drive a conversation one turn at a time. It's built for coding agents: you play the user, choose each next line based on the last reply, and inspect what the agent did in between.
Speech is off and nothing goes to a LiveKit room, so a turn costs only the agent's own LLM and tool calls. That's cheap enough to use constantly while building.
Before the first use, confirm the command exists and read its help:
bash
lk agent debugger --help
The help is thorough and is the source of truth for subcommands and flags, so this skill doesn't restate them. If the command is missing, the installed CLI predates it. Tell the user to update 
lk
and use 
testing-livekit-agents
until then. Don't guess at an older command's shape.
lk agent debugger
在本地以文本模式后台进程运行用户的agent，让你一次驱动一轮对话。它是为编码agent构建的：你扮演用户，根据最后一条回复选择下一行，并检查agent在期间做了什么。
语音关闭，不会进入LiveKit房间，因此一轮只花费agent自身的LLM和工具调用。这足够便宜，可以在构建时持续使用。
首次使用前，确认命令存在并阅读其帮助：
bash
lk agent debugger --help
帮助很详尽，是子命令和标志的权威来源，因此本技能不重复它们。如果命令缺失，则安装的CLI版本较旧。告诉用户更新
lk
，同时使用
testing-livekit-agents
。不要猜测旧版命令的形式。

The loop

循环

Start the agent, say user turns, inspect what happened, edit the code, restart, repeat, and stop when you're done. Roughly:
bash
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
Each 
say
prints everything the agent did in response (tool calls with arguments and results, handoffs, errors) followed by the reply. Between turns you can look at the agent's chat history, a live event stream, the process logs, and status; 
--help
lists the subcommands.
Restart after every code edit. A running session keeps the old code, and it's easy to lose time debugging behavior the file no longer has.
启动agent，发出用户轮次，检查发生了什么，编辑代码，重启，重复，完成后停止。大致如下：
bash
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
列出子命令。
**每次代码编辑后重启。**运行中的会话保留旧代码，很容易浪费时间调试文件已不再有的行为。

Debugging with it

使用它调试

  • Read the tool calls as well as the reply. The reply shows what went wrong; the tool call and its arguments usually show why. A wrong argument points to the prompt or the tool description. No call at all usually means the tool description never says when to use it.
  • Interleave the logs when a tool misbehaves. An option shows the agent's log lines under the turn they belong to, so a tool's traceback appears right below the sanitized error the user would have heard. That's the quickest way from symptom to cause.
  • Check the agent's chat history instead of relying on your memory of the conversation. It records what the LLM saw, including instruction and tool changes across handoffs. When behavior seems impossible, the history usually shows the context isn't what you assumed.
  • Reproduce before you fix, then re-run the same turns. Keep the sequence of 
    say
    lines that triggered the bug so you can compare before and after.
  • Drive whole conversations. Most bugs take several turns to show up: details collected early that get lost, a user changing their mind mid-flow, a handoff that drops context. A single turn won't find them.
  • Script it if a program is deciding the turns. There's machine-readable output and meaningful exit codes. Check 
    --help
    for the current format instead of assuming field names.
  • **同时阅读工具调用和回复。**回复显示出了什么问题；工具调用及其参数通常显示原因。错误的参数指向提示词或工具描述。完全没有调用通常意味着工具描述从未说明何时使用。
  • **当工具行为异常时插入日志。**一个选项可以在其所属轮次下显示agent的日志行，因此工具的回溯会出现在用户可能听到的经过清理的错误正下方。这是从症状到原因的最快路径。
  • **检查agent的聊天历史，而不是依赖你对对话的记忆。**它记录了LLM看到的内容，包括跨交接的指令和工具更改。当行为看似不可能时，历史通常显示上下文并非你所假设的。
  • **先复现再修复，然后重新运行相同的轮次。**保留触发bug的
    say
    行序列，以便前后比较。
  • **驱动整个对话。**大多数bug需要多轮才能显现：早期收集的细节丢失、用户中途改变主意、交接丢失上下文。单轮无法发现它们。
  • **如果程序决定轮次，则编写脚本。**有机器可读输出和有意义的退出码。查看
    --help
    了解当前格式，而不是假设字段名。

When to use something else

何时使用其他工具

SituationUse
You want to hear it, or hand the user something to try
lk agent console
(mic and speakers, a human at the keyboard)
The same failure keeps coming backA turn-level regression test (
testing-livekit-agents
)
You need whole-conversation outcomes graded at scaleSimulations (
running-livekit-simulations
)
The bug is about speech: turn-taking, interruptions, transcriptionAudio simulations. The debugger is text-only and can't see these
The debugger is for finding bugs interactively. Once you've found one, write a test for it so a later change can't reintroduce it unnoticed.
情况使用
你想听它，或交给用户尝试
lk agent console
（麦克风和扬声器，键盘前的人）
同样的失败不断出现轮次级回归测试（
testing-livekit-agents
）
你需要大规模评估整个对话结果模拟（
running-livekit-simulations
）
bug与语音有关：轮次切换、中断、转录音频模拟。调试器仅文本，无法看到这些
调试器用于交互式发现bug。一旦找到，为它编写测试，以便以后的更改无法在无人注意的情况下重新引入。

Related skills

相关技能

  • Building the agent: 
    building-livekit-agents
  • Pinning a found bug as a test: 
    testing-livekit-agents
  • Whole-conversation checks: 
    writing-livekit-scenarios
    , 
    running-livekit-simulations
  • Production-only failures (worker processes, providers, shutdown): 
    operating-livekit-agents
  • CLI flags and API facts: 
    reading-livekit-docs
  • 构建agent：
    building-livekit-agents
  • 将发现的bug固定为测试：
    testing-livekit-agents
  • 整个对话检查：
    writing-livekit-scenarios
    、
    running-livekit-simulations
  • 仅生产环境故障（worker进程、提供者、关闭）：
    operating-livekit-agents
  • CLI标志和API事实：
    reading-livekit-docs