Agent debugger | LiveKit Documentation

Overview

The lk agent debugger command runs your agent locally in text mode and lets a script or coding agent drive a conversation with it, one turn at a time. For how and when to use it, see CLI Agent Debugger.

LiveKit CLI v2.18.8 introduced the debugger. lk agent dbg is short for lk agent debugger.

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

A running session keeps the code it started with. Run restart after every edit to the agent.

Sessions

A session is one agent process plus the conversation it's having. The debugger runs one session per local port, on port 8775 by default. Every subcommand connects to the session on that port, so start, say, and stop can run from different shells or processes.

To run several agents side by side, give each one its own port with --port, or set the LK_SESSION_PORT environment variable. Pass the same port to every subcommand for that session.

A session stops itself after 30 minutes without any command, so a forgotten session doesn't leave an agent process running. Change this with start --idle-timeout.

Entrypoint detection

The debugger finds your agent the same way as the other local development commands: the project in the current directory (or the nearest parent) with its default entrypoint, or the file you name explicitly. Arguments after -- go to the Node.js or Python runtime.

The agent reads its own .env file for credentials, as it does with lk agent console.

Commands

Every subcommand accepts --port to select the session.

start

Launch the agent as a detached process and return once it's connected and ready for text turns. If the agent speaks first (for example, a greeting from on_enter), start prints it. The summary line names the active agent and its tools, and the path of the agent's log file.

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 any command. Takes a duration with a unit, such as `30m`, `2h`, or `90s`. Use `0` to keep it running until `stop`. Default: `30m`.
`--json`, `-j`	Print the greeting events and session status as JSON.

Only one session runs per port. If a session is already running, start fails. Use restart to replace it, or --port to run another.

# Name the entrypoint explicitly
lk agent debugger start src/my_agent.py

# Pass an option to Node.js
lk agent debugger start agent.ts -- --env-file=.env

say

Send one user turn and print what the agent does until the turn completes: tool calls with their arguments and results, handoffs to other agents, config changes, errors, and the reply. Anything the agent said since the previous turn, such as a message from a timer, prints first, labeled (before this turn).

lk agent debugger say [options] <text>

Option	Description
`--timeout DURATION`	Stop waiting for the agent's reply after this long. 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.
`--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.

The exit code is non-zero if the agent reported an error or the turn timed out. The agent keeps running either way.

Use --logs when a tool misbehaves. It places a tool's traceback directly under the error the user would have heard, which is usually the quickest way from symptom to cause.

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 own chat history. This reflects exactly what the LLM has seen: user and agent messages, tool calls with results, handoffs, and changes to instructions and tools. It works while a turn is in progress. transcript is an alias.

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

events

Stream the session's events as a flat, timestamped feed, one line each, until interrupted. The feed includes user and agent messages, tool calls with arguments and results, handoffs, config changes, errors, and agent state transitions. It observes without taking part, so it works alongside say from another shell or a script driving the session.

lk agent debugger events [options]

Option	Description
`--last N`, `-n N`	Number of recent events to print 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.
`--json`, `-j`	Print one JSON object per line (NDJSON), for piping into `jq` or another program.

status

Show whether a session is running and what it's doing: the project and entrypoint, the agent process ID, the active agent (after any handoffs) with its state and tools, the first line of its instructions, the number of turns so far, and the path of the agent's log file.

lk agent debugger status [--json]

status exits with code 1 when no session is running. With --json, it prints "running": false instead of an error, and includes the active agent's full instructions when a session is running.

logs

Print the agent process's recent output. The debugger also keeps the whole log in a file, and status shows its path. To see only the lines from a single turn, use say --logs.

lk agent debugger logs [options]

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

restart

Stop the running session and start a new one with the same entrypoint and port. The agent process relaunches, so code changes take effect and the conversation starts fresh. The new greeting, if any, prints as it does for start.

lk agent debugger restart [--json]

stop

Shut the agent down and print a closing summary: how many turns ran, for how long, which agent was active at the end, and where the agent's log file is.

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 any command for machine-readable output. A say turn prints a single JSON object:

{
  "text": "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 output has the following fields:

text: The user turn.
events: Everything the agent did during the turn, in order.
reply: The agent's reply text for the turn.
duration_ms: How long the turn took.
silent: true when the agent produced no output. Omitted otherwise.
error: The error message, 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`, when the agent reported them).
`tool_call`	`name`, `arguments`, `output`, and `is_error`. `output` is absent while a call is still running.
`handoff`	`from` and `to`, the agents involved. The session's first agent appears as a handoff with no `from`.
`config`	`changes`, a list of updates to the agent's instructions or tools.
`error`	`text`, the error the agent reported.
`log`	`text`, one line of the agent's log output.
`state`	`from` and `to`, an agent state transition. Reported only by `events`, never inside a turn.

Events can also include time (RFC 3339 with milliseconds), and earlier, which marks an event that happened before the turn it's reported with, such as an opening greeting or speech between turns.

Exit codes

Every command exits with a non-zero code when no session is running on the port. say also exits non-zero when the agent reports an error or the turn times out. Scripts can use these codes to detect failures without parsing output.