Terminal
Terminal/Skill
Drives a live conversation with a locally running LiveKit agent using the lk CLI, to check its behaviour and tool calls.
By LiveKit
Works with
npx skills add livekit/agent-skills --skill debugging-livekit-agentslk 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.
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.
say lines that
triggered the bug so you can compare before and after.--help for the current format instead of assuming field names.Text mode skips STT and TTS, so it can't show a name heard as a different spelling, digits the STT
spells out as words, a turn that ends too early, or anything from a realtime model that only takes
audio. Where the CLI supports it, starting the session with audio (check start --help) speaks
each say with LiveKit Inference TTS into the agent's microphone input, and the agent runs its full
audio pipeline.
lk must
have project credentials. Text mode doesn't need them.Audio mode still can't interrupt the agent mid-reply or tell you how the agent sounds. Use
lk agent console or audio simulations for those.
| Situation | Use |
|---|---|
| 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 back | A turn-level regression test (testing-livekit-agents) |
| You need whole-conversation outcomes graded at scale | Simulations (running-livekit-simulations) |
| Transcription or endpointing on a turn you're investigating | The debugger in audio mode (above) |
| Interruptions, or speech behavior graded across many conversations | Audio simulations (running-livekit-simulations) |
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.
building-livekit-agentstesting-livekit-agentswriting-livekit-scenarios, running-livekit-simulationsoperating-livekit-agentsreading-livekit-docs