Agent testing

Overview

Use these commands to test your agent without a person at the microphone:

lk agent debugger lets a script or coding agent converse with your local agent one turn at a time, in text or audio.
lk agent simulate runs Agent Simulations: whole conversations with LLM-driven simulated users, scored by a judge.

To talk to your agent yourself, use lk agent console. To install the CLI, see Install the CLI.

Agent debugger

Run your agent locally and drive a conversation with it from a script or coding agent. For a guide, see CLI Agent Debugger. lk agent dbg is an alias. Requires LiveKit CLI v2.19.0 or later.

Typical workflow

Run the commands from your agent's project directory:

# Start the agent and print its greeting, if any
lk agent debugger start

# Send user turns
lk agent debugger say "Hi, what can you do?"
lk agent debugger say "Book me a table for two tonight"

# Inspect the session between turns
lk agent debugger logs --last 40
lk agent debugger chat-history

# Pick up a code change with a fresh conversation
lk agent debugger restart

# Stop the agent and print a closing summary with the conversation
lk agent debugger stop --chat-history

Run restart after every code change; a running session keeps the code it started with.

Session modes

By default, a session is text: the agent runs with STT and TTS off, so a turn costs only your LLM and tool usage.

Start with --audio to speak each say line into the agent's microphone input using LiveKit Inference TTS. The agent runs its full audio pipeline, which catches problems text skips, such as misheard names, spelled-out digits, and endpointing. The microphone input is a continuous realtime stream with silence between turns, so endpointing behaves as it does on a call.

In audio mode, a turn lasts until the agent has transcribed the speech, responded, and then stayed silent for a few seconds. say shows what the agent transcribed, with the sent text beneath it when the two differ, for example (sent: "My order number is 4 8 1 5."). A turn the agent hears but never answers is reported as silent.

Audio-mode TTS is billed to your LiveKit Cloud project, which the debugger resolves like other lk commands: --project, LIVEKIT_* environment variables, livekit.toml, or the default project. It passes those credentials to the session under separate names, so the agent still reads its own from .env. The mode lasts for the whole session, including across restart.

Sessions

A session is one agent process and its conversation. The debugger runs one session per local port (default 8775), so subcommands can run from different shells. To run several agents side by side, give each its own port with --port or LK_SESSION_PORT, and pass that port to every subcommand.

A session stops after 30 minutes without a command. Change this with start --idle-timeout.

Entrypoint detection

The debugger finds your agent like the other local development commands. The agent reads credentials from its own .env file.

Commands

Every subcommand accepts --port to select the session.

start

Launch the agent in the background and return once it's ready. Prints the agent's greeting, if any, and a summary with the active agent, its tools, and the log path.

lk agent debugger start [options] [entrypoint] [-- runtime-args]

Option	Description
`--port PORT`	Local port for the session. Default: `8775`.
`--idle-timeout DURATION`	Stop the session after this long without a command, such as `2h`. Use `0` to run until `stop`. Default: `30m`.
`--audio`	Speak each turn instead of sending text. See Session modes.
`--json`, `-j`	Print the greeting events and session status as JSON.

If a session is already running on the port, start fails. Use restart to replace it, or --port to run another.

lk agent debugger start src/my_agent.py --audio

say

Send one user turn and print everything the agent does until it completes: tool calls and results, handoffs, config changes, errors, and the reply. Anything the agent said since the previous turn prints first, labeled (before this turn).

lk agent debugger say [options] <text>

Option	Description
`--timeout DURATION`	Stop waiting for the reply after this long. Default: `2m`.
`--logs`	Show the turn's log lines under the step they belong to. Useful for finding a tool's traceback.
`--metrics`	Show time to first token for each reply and how long the turn took.
`--json`, `-j`	Print the turn as a JSON document. See JSON output.

You can also pipe the text on stdin:

echo "Book me a table for two" | lk agent debugger say

chat-history

Print the conversation so far from the agent's chat history, which is exactly what the LLM has seen. Works during a turn. transcript is an alias.

lk agent debugger chat-history [--metrics] [--json]

events

Stream the session's events as a timestamped feed until interrupted, including agent state transitions. It only observes, so it works alongside say from another shell.

lk agent debugger events [options]

Option	Description
`--last N`, `-n N`	Recent events to print before streaming. Use `0` for all kept events (up to 500). Default: `50`.
`--logs`	Include the agent's log lines in the stream.
`--json`, `-j`	Print one JSON object per line (NDJSON).

status

Show whether a session is running, with its entrypoint, mode, active agent and tools, turn count, and log path.

lk agent debugger status [--json]

With --json, it also includes the active agent's full instructions. When no session is running, it prints "running": false and exits non-zero.

logs

Print the agent process's recent output. For a single turn's lines, use say --logs.

lk agent debugger logs [options]

Option	Description
`--last N`, `-n N`	Recent lines to print. Use `0` for the whole log. Default: `50`.
`--follow`, `-f`	Keep streaming new lines until interrupted.

restart

Relaunch the agent with the same entrypoint and port, picking up code changes and starting a fresh conversation.

lk agent debugger restart [--json]

stop

Shut the agent down and print a summary of the session.

lk agent debugger stop [options]

Option	Description
`--chat-history`	Also print the full conversation.
`--logs`	Also print the agent process's entire log.
`--metrics`	Show latency metrics with the conversation.
`--json`, `-j`	Print the summary, conversation, and logs in one JSON document.

JSON output

Add --json to start, say, chat-history, events, status, restart, or stop for machine-readable output. A say turn prints one object:

{
  "text": "Book me a table for two tonight",
  "heard": "Book me a table for two tonight",
  "events": [
    {
      "type": "tool_call",
      "name": "check_availability",
      "arguments": "{\"party_size\": 2, \"date\": \"2026-09-23\"}",
      "output": "{\"times\": [\"19:00\", \"20:30\"]}"
    },
    {
      "type": "message",
      "role": "assistant",
      "text": "I have tables at 7 and 8:30 tonight. Which works for you?"
    }
  ],
  "reply": "I have tables at 7 and 8:30 tonight. Which works for you?",
  "duration_ms": 2140
}

The turn object has these fields:

text: The user turn you sent.
heard: What the agent heard. Same as text in text mode; the transcript in audio mode.
events: Everything the agent did during the turn, in order.
reply: The agent's reply text.
duration_ms: How long the turn took.
silent: true when the agent produced no output. Omitted otherwise.
error: The error, when the turn failed or timed out. Omitted otherwise.

Each event has a type and the fields that apply to it:

Type	Fields
`message`	`role` (`user` or `assistant`), `text`, `interrupted`, and `metrics` (latencies in seconds, such as `llm_ttft`).
`tool_call`	`name`, `arguments`, `output` (absent while running), and `is_error`.
`handoff`	`from` and `to`. The first agent appears with no `from`.
`config`	`changes` to the agent's instructions or tools.
`error`	`text`.
`log`	`text`, one log line.
`state`	`from` and `to`. Reported only by `events`.

Events can also include time (RFC 3339) and earlier, which marks an event from before the turn, such as a greeting.

Exit codes

Every command exits non-zero when no session is running on the port. say also exits non-zero when the agent reports an error or the turn times out; the agent keeps running.

Agent Simulations

Run Agent Simulations against your agent, which the CLI starts locally by default, with the simulation running on LiveKit Cloud. lk agent simulation is an alias. Requires LiveKit CLI v2.19.0 or later.

lk agent simulate <subcommand> [options] [entrypoint]

Subcommands for simulate:

text [entrypoint]: Run scenarios in text mode.
audio [entrypoint]: Run scenarios through the full STT-LLM-TTS pipeline. See Simulate audio.
list: List recent runs. Accepts --limit N and --json.
view RUN_ID: Open a previous run.
export RUN_ID: Print a finished run and its chat contexts as JSON.
cancel RUN_ID: Cancel an in-progress run. Accepts --json.

The entrypoint follows entrypoint detection. A Node.js project with a build script must name its entrypoint, such as dist/main.js.

Options for text and audio, which you can also pass before the subcommand:

-n, --num-simulations N: Number of scenarios to generate from the agent's source. Ignored with --scenarios.
--scenarios FILE: Scenario file. If omitted, the CLI generates scenarios from the agent's source.
--concurrency N: Maximum parallel simulations in a run, up to 20. Default: 15. A project runs at most 30 at once.
--agent-name NAME: Run against an already-running agent instead of starting one. Pass "" for the project's default agent. Requires --scenarios.
--samples K, -k K: Run every scenario K times and report pass@k and pass^k. Requires --scenarios.
--pass-rate RATE: Share of samples, from 0 to 1, that must pass for a scenario to pass. Requires --samples. Default: 0.75.
--yes, -y: Skip confirmation prompts for the source upload and for adding scenario IDs. Required for non-interactive runs that would prompt.

Scenario IDs

A scenario file and each scenario in it need a stable id (SCNG_ for the file, SCN_ for scenarios), so LiveKit can track scenarios across runs. If IDs are missing, the CLI offers to add them in place; --yes adds them without asking.

Simulate audio

Run scenarios through the agent's full STT-LLM-TTS pipeline, with the simulated user speaking over an audio track.

lk agent simulate audio [options] [entrypoint]

audio accepts every text option, plus these flags that degrade the simulated user's audio:

--background-noise: Mix in ambient noise.
--low-quality-microphone: Simulate a low-quality microphone.
--packet-loss: Drop packets from the audio track.

Examples

Generate and run 10 scenarios from the agent's source:

lk agent simulate text -n 10

Run a checked-in scenario file:

lk agent simulate text --scenarios scenarios.yaml

Run scenarios over audio, with a noisy connection:

lk agent simulate audio --background-noise --packet-loss

Export a finished run as JSON:

lk agent simulate export RUN_ID > run.json