Skip to content
Skills Library
AI & agents · Testing

debugging-livekit-agents

/debugging-livekit-agents

Drives a multi-turn conversation with a LiveKit agent running locally to see what it does. Use when the user says "test my agent", "try my agent", "does this work", "why did it call that tool", "it says the wrong thing when I ask X", "test this change", or whenever you have edited an agent and need to check how it behaves. Wraps `lk agent debugger`: start the agent in text mode, send turns, read the tool calls, handoffs, errors and logs behind each reply, and restart after an edit. It runs without audio or a LiveKit room at one LLM call per turn, so it is the preferred way for a coding agent t

Licence
Apache-2.0
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Drives a multi-turn conversation with a LiveKit agent running locally to see what it does. Use when the user says "test my agent", "try my agent", "does this work", "why did it call that tool", "it says the wrong thing when I ask X", "test this change", or whenever you have edited an agent and need to check how it behaves. Wraps `lk agent debugger`: start the agent in text mode, send turns, read the tool calls, handoffs, errors and logs behind each reply, and restart after an edit. It runs without audio or a LiveKit room at one LLM call per turn, so it is the preferred way for a coding agent t

Triggers from the description

test my agenttry my agentdoes this workwhy did it call that toolit says the wrong thing when I ask Xtest this change
Original author description

Drives a multi-turn conversation with a LiveKit agent running locally to see what it does. Use when the user says "test my agent", "try my agent", "does this work", "why did it call that tool", "it says the wrong thing when I ask X", "test this change", or whenever you have edited an agent and need to check how it behaves. Wraps `lk agent debugger`: start the agent in text mode, send turns, read the tool calls, handoffs, errors and logs behind each reply, and restart after an edit. It runs without audio or a LiveKit room at one LLM call per turn, so it is the preferred way for a coding agent t

How it works

  1. The loop
  2. Debugging with it
  3. When to use something else
  4. Related skills
Original SKILL.md headings · 78 lines, 653 words
SKILL.md preview
---
name: debugging-livekit-agents
description: 'Drives a multi-turn conversation with a LiveKit agent running locally to see what it does. Use when the user says "test my agent", "try my agent", "does this work", "why did it call that tool", "it says the wrong thing when I ask X", "test this change", or whenever you have edited an agent and need to check how it behaves. Wraps `lk agent debugger`: start the agent in text mode, send turns, read the tool calls, handoffs, errors and logs behind each reply, and restart after an edit. It runs without audio or a LiveKit room at one LLM call per turn, so it is the preferred way for a coding agent to live-test during development, and the default when the user says "test" without naming unit tests or simulations.'
license: MIT
metadata:
  author: livekit
---

# Debugging a LiveKit agent live

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

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

## 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`) |
| The bug is about speech: turn-taking, interruptions, transcription | Audio 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.

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

Versions

RepositoryScoreLicence
This page · fcakyon/claude-codex-settings100Apache-2.0
livekit/agent-skills100MIT

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version ac1c19a818f8 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100livekit-agents
    Build voice AI agents with LiveKit Cloud and the Agents SDK. Use when the user asks to "build a voice agent", "create a LiveKit agent", "add voice AI", "implement handoffs", "structure agent workflows", or is working with LiveKit Agents SDK. Provides opinionated guidance for the…
  • 90testing-livekit-agents
    Writes 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…
  • 100running-livekit-simulations
    Runs 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…
  • 100building-livekit-agents
    Builds voice and chat AI agents with LiveKit Agents on LiveKit Cloud or a self-hosted server. 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…
  • 100running-livekit-simulations
    Runs 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…
  • 84voicetest
    Voice agent testing with voicetest. Activate when discussing voice agents, Retell, VAPI, LiveKit, Bland, Telnyx, agent graphs, conversation flow testing, or voicetest.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.