debugging-livekit-agents

Debugging a LiveKit agent live

lk agent debugger runs the user's agent locally as a background process 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.

By default the session is text: speech is off and nothing goes to a LiveKit room, so each turn is fast. When the bug lives in the audio path, start the session in audio mode instead (see Audio mode).

Before the first use, confirm the command exists and read its help:

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.

The loop

Start the agent, say user turns, inspect what happened, edit the code, restart, repeat, and stop when you're done. Roughly:

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.

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.