LiveKit docs › Reference › Developer tools › LiveKit CLI › Agent testing

---

# Agent testing

> Reference for lk agent debugger and lk agent simulate, the LiveKit CLI commands for testing agents.

## Overview

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

- `lk agent debugger` lets a script or [coding agent](https://docs.livekit.io/intro/coding-agents.md) converse with your local agent one turn at a time, in text or audio.
- `lk agent simulate` runs [Agent Simulations](https://docs.livekit.io/testing/simulations.md): whole conversations with LLM-driven simulated users, scored by a judge.

To talk to your agent yourself, use [`lk agent console`](https://docs.livekit.io/reference/developer-tools/livekit-cli/agent.md#console). To install the CLI, see [Install the CLI](https://docs.livekit.io/reference/developer-tools/livekit-cli.md#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](https://docs.livekit.io/testing/debugger.md). `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:

```shell
# 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](https://docs.livekit.io/reference/developer-tools/livekit-cli/agent.md#entrypoint-detection). 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.

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

```

Options for `debugger start`:

- `--port PORT`: Local PORT for the session. Default: `8775`. Also read from `LK_SESSION_PORT`.
- `--idle-timeout DURATION`: Stop the session after DURATION without any command. Takes a duration with a unit, such as 30m, 2h, or 90s. Use 0 to keep it running until stop. Default: `30m`.
- `--audio`: Speak each turn into the agent's microphone input instead of sending text, running its full audio pipeline. Uses LiveKit Inference TTS on your connected LiveKit Cloud project.
- `--json` (alias `-j`): Print the greeting events and session status as JSON.

For `--audio`, see [Session modes](#session-modes).

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

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

```shell
lk agent debugger say [options] <text>

```

Options for `debugger say`:

- `--port PORT`: Local PORT for the session. Default: `8775`. Also read from `LK_SESSION_PORT`.
- `--json` (alias `-j`): Print the turn as one JSON document.
- `--metrics`: Show time to first token for each reply and how long the turn took.
- `--timeout DURATION`: Stop waiting for the agent's reply after DURATION. Takes a duration with a unit, such as 2m or 90s. Default: `2m`.
- `--logs`: Show the agent's log lines emitted during the turn, beneath the step they belong to. Useful for finding a tool's traceback.

For the `--json` format, see [JSON output](#json-output).

You can also pipe the text on stdin:

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

```shell
lk agent debugger chat-history [options]
# or
lk agent debugger transcript [options]

```

Options for `debugger chat-history`/`debugger transcript`:

- `--port PORT`: Local PORT for the session. Default: `8775`. Also read from `LK_SESSION_PORT`.
- `--json` (alias `-j`): Print the chat history as one JSON document.
- `--metrics`: Show time to first token for each reply and how long the turn took.

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

```shell
lk agent debugger events [options]

```

Options for `debugger events`:

- `--port PORT`: Local PORT for the session. Default: `8775`. Also read from `LK_SESSION_PORT`.
- `--json` (alias `-j`): Print one JSON object per event, one per line (NDJSON).
- `--last N` (alias `-n`): Print the last N events before streaming new ones. Use 0 for every event kept, up to 500. Default: `50`.
- `--logs`: Include the agent's log lines in the stream.

#### status

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

```shell
lk agent debugger status [options]

```

Options for `debugger status`:

- `--port PORT`: Local PORT for the session. Default: `8775`. Also read from `LK_SESSION_PORT`.
- `--json` (alias `-j`): Print the session status as JSON, including the active agent's full instructions. With no session running, prints "running": false and exits 1.

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

```shell
lk agent debugger logs [options]

```

Options for `debugger logs`:

- `--port PORT`: Local PORT for the session. Default: `8775`. Also read from `LK_SESSION_PORT`.
- `--last N` (alias `-n`): Print the last N lines. Use 0 for the whole log. Default: `50`.
- `--follow` (alias `-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.

```shell
lk agent debugger restart [options]

```

Options for `debugger restart`:

- `--port PORT`: Local PORT for the session. Default: `8775`. Also read from `LK_SESSION_PORT`.
- `--json` (alias `-j`): Print the greeting events and session status as JSON, like start.

#### stop

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

```shell
lk agent debugger stop [options]

```

Options for `debugger stop`:

- `--port PORT`: Local PORT for the session. Default: `8775`. Also read from `LK_SESSION_PORT`.
- `--json` (alias `-j`): Print the summary, conversation, and logs in one JSON document.
- `--metrics`: Show latency metrics for each turn of the conversation. Requires `--chat-history`.
- `--chat-history`: Also print the full conversation.
- `--logs`: Also print the agent process's entire log.

### JSON output

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

```json
{
  "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](https://docs.livekit.io/testing/simulations.md) against your agent, which the CLI starts locally by default, with the simulation running on LiveKit Cloud. Requires LiveKit CLI `v2.19.0` or later. To run simulations with [user authentication](https://docs.livekit.io/reference/developer-tools/livekit-cli/auth.md#user-auth), add `--user-auth` to each command. This requires `v2.19.4` or later.

```shell
lk agent simulate <command> [options]
# or
lk agent simulation <command> [options]

```

Subcommands:

- `text [entrypoint]`: Run scenarios in text mode.
- `audio [entrypoint]`: Run scenarios through the full STT-LLM-TTS pipeline.
- `list`: List the project's most recent simulation runs.
- `view RUN_ID`: Open a previous run instead of starting a new one. No agent is started and nothing is dispatched.
- `export RUN_ID`: Print a finished run and its per-job chat contexts to stdout as JSON. The run must have finished: completed, failed, or cancelled.
- `get RUN_ID`: Get a simulation run by ID (requires `--user-auth`).
- `cancel RUN_ID`: Cancel a run that's still in progress.

Options for `simulate`/`simulation`:

- `--num-simulations N` (alias `-n`): Number N of scenarios to generate from the agent's source. Has no effect when a scenario file is in use.
- `--concurrency N`: Maximum number N of simulations to run in parallel within a run. Defaults to 15 when unset. An explicit value can't exceed 20; a higher value is rejected. Separately, a project-wide limit of 30 running simulations applies across all runs.
- `--samples K` (alias `-k`): Run every scenario K times in one run, and report pass@k (passed at least once) and pass^k (passed every time). Requires `--scenarios` when K is more than 1. LiveKit Cloud accepts 1 or 3. Each sample counts as a separate simulation, and the number of scenarios multiplied by K can't exceed the limit of 250 simulations per run.
- `--pass-rate RATE`: Share of samples that must pass for a scenario to pass, as a RATE greater than 0 and at most 1. Rounds to whole samples with a minimum of one; for example, 0.75 of 3 samples needs 2 passes. Requires `--samples` of more than 1. Default: `0.75`.
- `--scenarios FILE`: Path to a scenario FILE. If you omit it, the CLI generates scenarios from the agent's source. The file and every scenario in it need an id, and the CLI offers to add any that are missing.
- `--yes` (alias `-y`): Skip the confirmation prompts for the source upload and for adding missing IDs to the scenario file. Required for non-interactive runs that generate scenarios from source or run a file with missing IDs.
- `--agent-name NAME`: Run against an already-running agent instead of spawning one locally. Pass the registered NAME, or an empty string ("") to target the project's default agent that auto-joins every room. Requires `--scenarios`.
- `--deployment NAME`: NAME of the agent deployment to run against, such as a non-production deployment. Defaults to production. Requires `--agent-name`.

You can pass the `simulate` options before or after the `text` or `audio` subcommand name. To run against the [project's default agent](https://docs.livekit.io/agents/server/agent-dispatch.md), pass `--agent-name ""`. To run against a [non-production deployment](https://docs.livekit.io/deploy/agents/deployments.md) of a live agent, add `--deployment NAME`. For audio runs, see [Simulate audio](#simulate-audio).

The entrypoint follows [entrypoint detection](https://docs.livekit.io/reference/developer-tools/livekit-cli/agent.md#entrypoint-detection). A Node.js project with a `build` script must name its entrypoint, such as `dist/main.js`.

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

```shell
lk agent simulate text [options] [entrypoint]

```

Also takes the options for `simulate`.

### Simulate audio

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

```shell
lk agent simulate audio [options] [entrypoint]

```

Options for `simulate audio`:

- `--background-noise`: Mix ambient noise into the simulated user's audio.
- `--low-quality-microphone`: Publish the simulated user's audio as a low-quality microphone would capture it.
- `--packet-loss`: Drop packets from the simulated user's audio track.
- `--to NUMBER`: Call this NUMBER (or SIP user) and simulate against whoever answers, instead of dispatching an agent. Requires `--from` and `--scenarios`.
- `--trunk ID`: Outbound SIP trunk ID to place `--to` calls through. Without it, calls go out from a LiveKit phone number.
- `--from NUMBER`: Caller NUMBER for `--to` calls: a LiveKit phone number the project owns, or a number on `--trunk`.

Also takes the options for `simulate`.

To test an agent by calling its phone number, see [Test an agent by phone](https://docs.livekit.io/testing/simulations.md#test-by-phone).

### List runs

```shell
lk agent simulate list [options]

```

Options for `simulate list`:

- `--limit N`: Number N of runs to return. If unset, defaults to the API page size.
- `--status STATUS`: Filter by STATUS (running, completed, failed, cancelled, ...) (requires `--user-auth`).
- `--cursor CURSOR`: Page CURSOR from a prior `--json` listing (requires `--user-auth`).
- `--json` (alias `-j`): Output as JSON.

### Get a run

Print the details of a run. This command needs [user authentication](https://docs.livekit.io/reference/developer-tools/livekit-cli/auth.md#user-auth).

```shell
lk agent simulate get RUN_ID --project PROJECT --user-auth

```

Options for `simulate get`:

- `--json` (alias `-j`): Output as JSON.

### View a run

```shell
lk agent simulate view RUN_ID

```

### Export a run

```shell
lk agent simulate export RUN_ID

```

### Cancel a run

```shell
lk agent simulate cancel [options] RUN_ID

```

Options for `simulate cancel`:

- `--json` (alias `-j`): Output as JSON.

### Examples

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

```shell
lk agent simulate text -n 10

```

Run a checked-in scenario file:

```shell
lk agent simulate text --scenarios scenarios.yaml

```

Run every scenario 3 times. With the default pass rate of `0.75`, a scenario passes when at least 2 of its 3 samples pass:

```shell
lk agent simulate text --scenarios scenarios.yaml --samples 3

```

Run scenarios over audio, with a noisy connection:

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

```

Call a phone number and run scenarios against the agent that answers:

```shell
lk agent simulate audio --scenarios scenarios.yaml --to +14155550100 --from +14155550199 --trunk ST_xxxx

```

Export a finished run as JSON:

```shell
lk agent simulate export RUN_ID > run.json

```

---

This document was rendered at 2026-11-14T14:53:50.840Z.
For the latest version of this document, see [https://docs.livekit.io/reference/developer-tools/livekit-cli/agent/testing.md](https://docs.livekit.io/reference/developer-tools/livekit-cli/agent/testing.md).

To explore all LiveKit documentation, see [llms.txt](https://docs.livekit.io/llms.txt).