Server startup modes

Overview

The Agents SDK includes a CLI interface that make it easy to start your agent server in various modes. Each mode is optimized for specific use cases and development stages, from local testing to production deployments.

Your agent server can be started in the following modes:

These is also a one-time setup command, download-files, that downloads required runtime assets for plugins. To learn more see Download files.

Authentication

You must set authentication credentials before you start your agent server in order to connect to LiveKit and LiveKit Inference. They can be set in environment variables or passed as command-line arguments.

Set environment variables

Run the following LiveKit CLI command to load your LiveKit Cloud API keys into a .env.local file:

lk app env -w

The file should look like this:

LIVEKIT_API_KEY=<your API Key>
LIVEKIT_API_SECRET=<your API Secret> 
LIVEKIT_URL=<your LiveKit server URL>

Start mode

Start mode runs your agent server in production with proper error handling and graceful shutdown. This mode connects to LiveKit with settings optimized for production deployments.

Start mode provides the following features:

• Production logging: Log level defaults to INFO for clean output.
• Graceful shutdown: Drains active jobs before shutting down on SIGINT or SIGTERM signals.
• Production optimizations: Includes load balancing, overload protection, and pre-warmed idle processes to ensure high availability.

To start your agent server in production mode, use the following command:

uv run agent.py start

tsc && node agent.js start

Graceful shutdown

In production mode, when your agent server receives a shutdown signal (such as SIGTERM from a container orchestrator or Ctrl+C), it drains active jobs before closing:

1. Stops accepting new job assignments.
2. Waits for active jobs to complete (up to --drain-timeout in Python).
3. Closes all connections and cleans up resources.
4. Exits with appropriate status code.

Parameters

The following parameters are available in production mode:

Dev mode

In dev mode, your agent server starts with features optimized for local development, including enhanced logging and automatic code reloading:

• Debug logging: Log level defaults to DEBUG for detailed output.
• Auto-reload: In Python, auto-reloads when code changes are detected. For Node.js, use tsx for automatic Typescript complication and reloading.
• Development optimizations: No graceful shutdown drain period for faster iteration.

Start your agent server in dev mode with the following command:

uv run agent.py dev

tsx agent.ts dev

Parameters

The following parameters are available in dev mode:

Console mode

Console mode runs your agent server in your terminal without connecting to LiveKit. This single-session mode simulates a full agent session entirely on your local machine for quick testing and debugging during development.

Console mode allows you to interact with your agent using text or voice, and offers the following features:

• Audio I/O: Choose which local audio devices to use for input and output.
• Visual feedback: Displays audio input using a real-time frequency visualizer.
• Text mode: Toggle between audio and text-only interaction.
• Session recording: Record sessions to disk for playback and analysis.

Start your agent server in console mode with the following command:

uv run agent.py console

You can speak to your agent with text or voice.

Parameters

The following parameters are available in console mode:

Examples

Use these examples to run your agent in console mode with different configurations:

List available audio devices:

uv run agent.py console --list-devices

Run your agent in text-only mode:

uv run agent.py console --text

Specify input and output devices for audio:

uv run agent.py console --input-device "Macbook Pro Microphone" --output-device "External Headphones"

Record the session to disk:

uv run agent.py console --record

Connect mode

Connect mode starts your agent server with a direct connection to a specific LiveKit room. This single-session mode is useful for testing with live participants or debugging specific room scenarios.

uv run agent.py connect --room my-test-room

uv run agent.py connect --room my-room --participant-identity my-agent-1

pnpm tsx agent.ts connect --room my-test-room

pnpm tsx agent.ts connect --room my-room --participant-identity my-agent-1

Parameters

Download files

Some plugins require model files or other assets to be available at runtime. For example, the turn-detector, silero, and noise-cancellation plugins all require downloaded model files.

The download-files command downloads required external assets for these plugins. Run this command as part of your build process or before running your agent locally for the first time.

When executed, download-files calls each plugin's download-files() method to fetch its files. Any custom plugins that implement download-files() are invoked automatically.

The following command downloads files for the plugins your agent uses:

uv run agent.py download-files

tsc && node agent.js download-files

Add scripts in Node.js

If you're using Node.js, you can add the following scripts to your package.json file to start your agent server in different modes using pnpm:

{
  "scripts": {
    "dev": "tsx agent.ts dev",
    "build": "tsc",          
    "start": "tsc && node agent.js start",
    "connect": "tsx agent.ts connect",
    "download-files": "tsc && node agent.js download-files"
  }
}

For example, to start the agent in development mode, execute the following command:

pnpm dev