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:

  • AGENT-NAME: Project directory name and the agent's dispatch name. If omitted, defaults to the LiveKit Cloud project's name. If the CLI can't determine a project name, it prompts you.
  • --region REGION: Region code to deploy to. Defaults to the nearest region.
  • --lang LANGUAGE: Language of the starter template, python or node. If unset, the CLI asks, with Python preselected. Ignored when you pass --template or --template-url.
  • --install: Install the project's dependencies after creating it. If unset, the CLI asks. Pass --install=false to skip.
  • --deploy: Deploy the agent to LiveKit Cloud after initialization. Implies --install. Default: false.
  • --template TEMPLATE: Template to instantiate, such as agent-starter-python. See App templates.
  • --template-url URL: URL of a repository or archive to instantiate. It must have a taskfile.yaml at its root.
  • --sandbox NAME: Deprecated no-op.
  • --no-sandbox: Deprecated no-op. Default: false.
  • --skills: Install LiveKit Agent Skills and the Docs MCP server for your coding agents. If unset, the CLI asks. Pass --skills=false to skip.

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 region:

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

Dev

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

lk agent dev [command options] [entrypoint]

Options for dev:

  • --log-level LEVEL: One of TRACE, DEBUG, INFO, WARN, ERROR. Also accepts CRITICAL for Python and FATAL for Node.js.
  • --no-reload: Disable auto-reload on file changes.
  • --deployment ID: Deployment to register the agent under. Also read from LIVEKIT_AGENT_DEPLOYMENT, and overrides that value in the agent's .env file. Default: a random dev- ID. Pass production to serve production traffic.

Starting with LiveKit CLI v2.19.0, lk agent dev registers under a random dev- deployment so it doesn't take production jobs, and 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 [command options] [entrypoint]

Options for start:

  • --log-level LEVEL: One of TRACE, DEBUG, INFO, WARN, ERROR. Also accepts 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 [command options] [entrypoint]

Options for console:

  • --text, -t: Start in text mode instead of audio mode.
  • --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.
  • --record: Record audio and a session report to console-recordings/.
  • --port PORT, -p PORT: TCP port for agent communication. Default: 0 (auto-select).

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"