LiveKit Agents Starter - Python

A complete starter project for building voice AI apps with LiveKit Agents for Python and LiveKit Cloud.

The starter project includes:

• A simple voice AI assistant, ready for extension and customization
• Default behavior: a concise, friendly voice assistant that avoids complex formatting and punctuation
• A voice AI pipeline with models from OpenAI, Cartesia, and AssemblyAI served through LiveKit Cloud
  • Easily integrate your preferred LLM, STT, and TTS instead, or swap to a realtime model like the OpenAI Realtime API
• Eval suite based on the LiveKit Agents testing & evaluation framework
• LiveKit Turn Detector for contextually-aware speaker detection, with multilingual support
• Background voice cancellation
• Integrated metrics and logging
• A Dockerfile ready for production deployment

This starter app is compatible with any custom web/mobile frontend or SIP-based telephony.

Coding agents and MCP

This project is designed to work with coding agents like Cursor and Claude Code.

To get the most out of these tools, install the LiveKit Docs MCP server.

For Cursor, use this link:

For Claude Code, run this command:

claude mcp add --transport http livekit-docs https://docs.livekit.io/mcp

For Codex CLI, use this command to install the server:

codex mcp add --url https://docs.livekit.io/mcp livekit-docs

For Gemini CLI, use this command to install the server:

gemini mcp add --transport http livekit-docs https://docs.livekit.io/mcp

The project includes a complete AGENTS.md file for these assistants. You can modify this file to your needs. To learn more about this file, see https://agents.md.

Prerequisites

• Python >=3.10, <3.14
• The uv package manager

Dev Setup

Clone the repository and install dependencies to a virtual environment:

cd <your-project-directory>
uv sync

If you are on Intel macOS 11 or 12 and see an onnxruntime wheel error, run:

uv sync --python-platform x86_64-apple-darwin

Sign up for LiveKit Cloud then set up the environment by copying .env.example to .env.local and filling in the required keys:

• LIVEKIT_URL
• LIVEKIT_API_KEY
• LIVEKIT_API_SECRET
• AGENT_RUNTIME_NAME for the LiveKit dispatch target name, which must match your SIP dispatch rule
• ASSISTANT_NAME for the spoken name the caller hears
• AGENT_LOAD_THRESHOLD optional worker availability threshold (default 0.85)
• AGENT_IDLE_PROCESSES optional idle worker process count (default 1)
• AGENT_INIT_TIMEOUT_SECONDS optional worker process init timeout in seconds (default 30)

Model access options:

• LiveKit Cloud inference (default): models are served through LiveKit Cloud, no extra API keys required.
• Direct provider keys: if you swap to provider plugins, add the required API keys (e.g., OPENAI_API_KEY, ASSEMBLYAI_API_KEY, CARTESIA_API_KEY) to .env.local.

You can load the LiveKit environment automatically using the LiveKit CLI:

lk cloud auth
lk app env -w -d .env.local

Run the agent

Before your first run, you must download certain models such as Silero VAD and the LiveKit turn detector. If you skip this step, the agent will fail to start when it tries to load these assets:

uv run python src/agent.py download-files

If you used --python-platform during sync, run the agent commands with --no-sync:

uv run --no-sync python src/agent.py download-files

For example:

uv run --no-sync python src/agent.py console
uv run --no-sync python src/agent.py dev
uv run --no-sync python src/agent.py start

Next, run this command to speak to your agent directly in your terminal:

uv run python src/agent.py console

To run the agent for use with a frontend or telephony, use the dev command:

uv run python src/agent.py dev

In production, use the start command:

uv run python src/agent.py start

Frontend & Telephony

Get started quickly with our pre-built frontend starter apps, or add telephony support:

Platform	Link	Description
Web	livekit-examples/agent-starter-react	Web voice AI assistant with React & Next.js
iOS/macOS	livekit-examples/agent-starter-swift	Native iOS, macOS, and visionOS voice AI assistant
Flutter	livekit-examples/agent-starter-flutter	Cross-platform voice AI assistant app
React Native	livekit-examples/voice-assistant-react-native	Native mobile app with React Native & Expo
Android	livekit-examples/agent-starter-android	Native Android app with Kotlin & Jetpack Compose
Web Embed	livekit-examples/agent-starter-embed	Voice AI widget for any website
Telephony	📚 Documentation	Add inbound or outbound calling to your agent

For advanced customization, see the complete frontend guide.

Tests and evals

This project includes a complete suite of evals, based on the LiveKit Agents testing & evaluation framework. To run them, use pytest.

uv run pytest

Using this template repo for your own project

Once you've started your own project based on this repo, you should:

1. Check in your uv.lock: This file is currently untracked for the template, but you should commit it to your repository for reproducible builds and proper configuration management. (The same applies to livekit.toml, if you run your agents in LiveKit Cloud)

2. Remove the git tracking test: Delete the "Check files not tracked in git" step from .github/workflows/tests.yml since you'll now want this file to be tracked. These are just there for development purposes in the template repo itself.

3. Add your own repository secrets: You must add secrets for LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET so that the tests can run in CI.

Deploying to production

This project is production-ready and includes a working Dockerfile. To deploy it to LiveKit Cloud or another environment, see the deploying to production guide.

Self-hosted LiveKit

You can also self-host LiveKit instead of using LiveKit Cloud. See the self-hosting guide for more information. If you choose to self-host, you'll need to also use model plugins instead of LiveKit Inference and will need to remove the LiveKit Cloud noise cancellation plugin.

Troubleshooting

• Missing env vars: ensure .env.local includes LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET, or load them via lk app env -w -d .env.local.
• Telephony dispatch mismatch: AGENT_RUNTIME_NAME must match the agent name in your SIP dispatch rule. ASSISTANT_NAME only affects the spoken introduction.
• Model download failures: re-run uv run python src/agent.py download-files and verify your network access to the model artifacts.
• CI wrapper failures can be transient if a sync or another run is happening at the same time. If that happens, retry after the workspace settles.
• Turn detector startup error (model_q8.onnx missing): run uv run python src/agent.py download-files before starting the worker.
• Port in use ([Errno 48] ... 8081): another worker is already running; stop existing workers before starting a new one.
• Worker toggles unavailable under load: lower AGENT_IDLE_PROCESSES or raise AGENT_LOAD_THRESHOLD in .env.local.

License

This project is licensed under the MIT License - see the LICENSE file for details.