debugging-livekit-agents

$npx mdskill add expo/expo-livekit-template/debugging-livekit-agents

`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.

SKILL.md

.github/skills/debugging-livekit-agentsView on GitHub ↗
---
name: debugging-livekit-agents
description: 'Drives a live multi-turn conversation with a LiveKit agent running locally, using `lk agent debugger`. Use when the user says "test my agent", "try my agent", "does this work", or "why did it call that tool", after editing an agent to check how it behaves, or when an agent on a speech-to-speech model or one that mishears users needs checking. The default for a bare "test"; for regression tests use testing-livekit-agents, for graded runs running-livekit-simulations.'
license: MIT
metadata:
  author: livekit
---

# 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](#audio-mode)).

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.

## 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.

## 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.

## Audio mode

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.

- **Use it when the symptom is about hearing**, or when the agent uses a speech-to-speech model that
  can't run in text mode. Stay in text mode for logic, prompt, and tool bugs: it's faster, and
  the transcription noise only gets in the way.
- **It needs a LiveKit Cloud project.** The spoken turns run on LiveKit Inference, so `lk` must
  have project credentials. Text mode doesn't need them.
- **Compare what was heard with what you sent.** Each turn shows the agent's transcript of your
  line, and the sent text when the words differ. That difference is often the whole bug: the agent
  answered correctly to what it heard.
- **Write lines the way a caller would say them.** Spell out numbers and codes when testing how the
  agent handles spoken input, and test both forms if the agent should accept either.
- **The mode belongs to the session.** Restart keeps it; stop and start again to switch.
- **A long silent pause can end a turn early.** A turn ends once the agent has answered and stayed
  quiet for a moment. If the agent pauses for a long time before finishing (for example, a realtime
  model waiting on a delegated answer), the rest of its reply shows up in the next turn. Check the
  chat history before concluding the agent never answered.

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.

## When to use something else

| 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.

## 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`

More from expo/expo-livekit-template

SkillDescription
building-livekit-agentsBuilds voice and chat AI agents with LiveKit Agents and LiveKit Cloud. Use when the user asks to "build a voice agent", "create a LiveKit agent", "add voice AI to my app", "implement handoffs", "structure an agent workflow", "my agent is slow / too chatty", "it says it booked but nothing was saved", "make it confirm before committing", "it keeps re-asking things the caller already said", or is writing code against the LiveKit Agents SDK. Covers architecture: designing for latency, keeping context small, splitting a monolithic agent into handoffs and tasks, and designing for voice. Also covers keeping the model in charge of meaning while code owns state, approvals, and effects. For API specifics use reading-livekit-docs. To check behavior use debugging-livekit-agents and testing-livekit-agents.
operating-livekit-agentsDeploys and operates a LiveKit agent in production: shipping a version to LiveKit Cloud and rolling it back, secrets and configuration, the worker process model and prewarming, safe async inside worker processes, provider timeouts and degradation, graceful shutdown, SDK upgrades, and observability. Use when the user says "deploy my agent", "roll back the deployment", "tail the agent logs", "the first call after a restart is slow", "attached to a different loop / event loop is closed", "prewarm the VAD", "shut down without dropping calls", "upgrade livekit-agents safely", "correlate logs by session", or is changing an agent codebase that is already live. Not for designing the agent (building-livekit-agents) or reproducing one bad conversation locally (debugging-livekit-agents).
reading-livekit-docsLooks up current LiveKit facts (API signatures, CLI flags, config options, model and provider support, SDK changelogs, pricing) from the docs instead of answering from memory. Use whenever a question touches LiveKit specifics: "does LiveKit support X", "what changed in agents 1.8", "what are the arguments to Y", "how much does LiveKit cost", "find an example of Z in the LiveKit repos", or before writing any LiveKit code. Other LiveKit skills load this one first. Covers the LiveKit Docs MCP server and the `lk docs` CLI.
running-livekit-simulationsRuns LiveKit agent simulations and acts on the results. Use when the user says "run my simulations", "regression test my agent before deploying", "run the scenarios", "use lk agent simulate", "did my agent pass", "why did this scenario fail", "run simulations in CI", "test the audio pipeline", "check turn-taking and interruptions", or wants to check whole-conversation behavior before shipping. Covers text and audio mode and what each catches, running against a local or deployed agent, degraded-audio flags, automating a pre-release run, and triaging failures with list, view and export. For writing the scenarios use writing-livekit-scenarios. Not the default for a bare "test my agent", which goes to debugging-livekit-agents. Use this skill when the user names simulations, scenarios, a run, CI, or shipping.
testing-livekit-agentsWrites turn-level tests for a LiveKit agent in the user''s normal test suite: pytest (Python) or Vitest (Node.js). Use when the user asks to "write tests for my agent", "add a test for this tool", "test the handoff", "pin this bug", "why does my agent test fail", or after building or changing agent behavior that needs regression coverage. Covers the SDK''s test session harness, assertions on messages, tool calls and handoffs, LLM judging of a reply against an intent, mocking tools, multi-turn tests, and judging whole conversations with the built-in judges. For interactive poking use debugging-livekit-agents. For grading whole conversations at scale use running-livekit-simulations.
writing-livekit-scenariosCreates and maintains the scenarios a LiveKit agent simulation runs, and wires the agent to consume them. Use when the user asks "what should I test", "generate simulation scenarios", "write scenarios for my agent", "add a scenario for X", "organize my scenario files", "my simulations are flaky", "the scenario hits my real database", "seed state per scenario", "it passed but booked the wrong thing", "grade the final state", or wants to stress-test a flow before shipping. Covers generating a baseline with the LiveKit scenario generator and refining it, writing the cases generation misses, phrasing simulated-user instructions so they steer reliably, splitting scenarios into sets across files, and the agent-side code that seeds deterministic state from a scenario and fails a run on its final state. To run them use running-livekit-simulations.