Skip to main content
IntroductionBuild AgentsAgent FrontendsTest & EvaluateTelephonyRoboticsWebRTC TransportManage & DeployReferences
XYouTubeSlack

Agent development

Reference for the LiveKit CLI commands that scaffold an agent and run it locally.

On this page

Overview Entrypoint detection Init Examples Dev Examples Start Examples Console Examples

Overview

Use lk agent commands to develop and test agents locally, or to deploy and manage agents on LiveKit Cloud. You can abbreviate lk agent as lk a. To install the CLI, see Install the CLI.

The agent commands are grouped by task:

Entrypoint detection

The dev, start, console, debugger, and simulate commands accept an optional entrypoint. Arguments after -- go to the Node.js or Python runtime, not to your agent.

When you omit entrypoint, the CLI finds the project manifest (package.json, uv.lock, requirements.txt, or pyproject.toml) in the working directory or a parent, then looks for agent.py or src/agent.py for Python, and main.ts, src/main.ts, or src/main.js for Node.js.

The starter templates match these defaults, so you can run commands from the project root with no argument. Pass an explicit path for any other filename, such as a single-file recipe:

lk agent console answer_call.py

Init

Scaffold a new agent project (Python or Node.js) from a template, and optionally deploy it to LiveKit Cloud.

lk agent init [options] [AGENT-NAME]

Options for init:

  • --region REGION: REGION code to deploy the agent to. Used only with --deploy. If unset, the CLI prompts you to select a region. Required in non-interactive mode.
  • --install: Install the project's dependencies after creating it. If unset, the CLI asks. Skipped in non-interactive mode. Pass --install=false to skip.
  • --skills: Install LiveKit Agent Skills and the Docs MCP server for your coding agents (see lk skills). If unset, the CLI asks. Automatically installed in non-interactive mode. Pass --skills=false to skip.
  • --lang LANGUAGE: LANGUAGE of the starter template. One of python, node. If unset, the CLI asks, with Python preselected. Defaults to Python in non-interactive mode. Ignored with --template or --template-url.
  • --deploy: Deploy the agent to LiveKit Cloud after initialization. Implies --install.
  • --template TEMPLATE: TEMPLATE to instantiate. For example, agent-starter-python or agent-starter-node. See https://github.com/livekit-examples for the full list.
  • --template-url URL: Custom URL to a repository or archive to instantiate (for example, a Git repo URL). The project at that URL must include a taskfile.yaml file at its root.

AGENT-NAME is the project directory name and the agent's dispatch name. If omitted, it defaults to the LiveKit Cloud project's name. If the CLI can't determine a project name, it prompts you.

See Region codes for --region values, App templates for --template, and Agent Skills for --skills.

Examples

Initialize a named agent and deploy it in one step:

lk agent init my-voice-agent --deploy

Initialize a Node.js agent:

lk agent init my-agent --lang node

Initialize from a specific template and deploy it to a region:

lk agent init my-agent --template agent-starter-python --region us-east --deploy

Dev

Run the agent locally in development mode, with colored logs and auto-reload on file changes. See Entrypoint detection.

lk agent dev [options] [entrypoint] [-- node/python-args...]

Options for dev:

  • --log-level LEVEL: Log LEVEL. One of TRACE, DEBUG, INFO, WARN, ERROR, plus CRITICAL for Python and FATAL for Node.js.
  • --no-reload: Disable auto-reload on file changes.
  • --deployment NAME: Deployment NAME to register the agent under. Defaults to a random dev- ID so dev traffic is isolated from production; pass production to explicitly serve production traffic. Overrides any value in the agent's .env file. Also read from LIVEKIT_AGENT_DEPLOYMENT.

The random dev- deployment default requires LiveKit CLI v2.19.0 or later. lk agent dev prints an Agent Console link that targets it. To dispatch to it another way, use lk token create --deployment.

Examples

Run the auto-detected entrypoint at the debug log level:

lk agent dev --log-level DEBUG

Register under the staging deployment:

lk agent dev --deployment staging

Start

Run the agent locally in production mode, with clean logging and graceful shutdown on SIGINT or SIGTERM. This is how deployed agents run. See Entrypoint detection.

lk agent start [options] [entrypoint] [-- node/python-args...]

Options for start:

  • --log-level LEVEL: Log LEVEL. One of TRACE, DEBUG, INFO, WARN, ERROR, plus CRITICAL for Python and FATAL for Node.js.

Examples

Pass an environment file to Node.js:

lk agent start -- --env-file=.env.production

Console

Talk to your agent through your computer's microphone and speakers, in a simulated room that doesn't connect to LiveKit Cloud. The simulated room has no job metadata; to test with metadata, use the Agent Console. To let a coding agent or script drive the conversation, use the debugger. See Entrypoint detection.

lk agent console [options] [entrypoint] [-- node/python-args...]

Options for console:

  • --port PORT (alias -p): TCP PORT for agent communication. Defaults to 0 (auto-select).
  • --input-device NAME: Input device index or NAME substring.
  • --output-device NAME: Output device index or NAME substring.
  • --list-devices: List available audio devices and exit.
  • --no-aec: Disable acoustic echo cancellation.
  • --text (alias -t): Start in text mode instead of audio mode.
  • --record: Record audio and a session report to console-recordings/.

Examples

Start in text mode:

lk agent console --text

Select specific audio devices:

lk agent console --input-device "MacBook Pro Microphone" --output-device "External Headphones"