LiveKit Agents Starter - Python

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

The starter project includes:

• A simple voice AI assistant based on the Voice AI quickstart
• Voice AI pipeline based on OpenAI, Cartesia, and Deepgram
  • 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
• LiveKit Cloud enhanced noise cancellation
• Integrated metrics and logging

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

Dev Setup

Clone the repository and install dependencies to a virtual environment:

cd agent-starter-python
uv sync

Set up the environment by copying .env.example to .env.local and filling in the required values:

• LIVEKIT_URL: Use LiveKit Cloud or run your own
• LIVEKIT_API_KEY
• LIVEKIT_API_SECRET
• OPENAI_API_KEY: Get a key or use your preferred LLM provider
• DEEPGRAM_API_KEY: Get a key or use your preferred STT provider
• CARTESIA_API_KEY: Get a key or use your preferred TTS provider

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

lk app env -w .env.local

Run the agent

Before your first run, you must download certain models such as Silero VAD and the LiveKit turn detector:

uv run python src/agent.py download-files

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

Container Execution Context

Important: This agent uses uv for dependency management and virtual environment isolation. All Python execution must use uv run to ensure proper access to dependencies.

Why uv run is required

The container uses uv-managed virtual environments rather than system-wide Python package installation. This provides:

• Dependency isolation: Prevents conflicts between project dependencies and system packages
• Reproducible builds: Locked dependency versions ensure consistent behavior across environments
• Security: Non-root user execution in isolated environment

Execution contexts

• ✅ Correct: uv run python src/agent.py start
• ❌ Incorrect: python src/agent.py start (will fail with ModuleNotFoundError)

Health monitoring

The agent includes built-in health checks for monitoring system status:

• Environment variables: Validates required configuration
• RAG connectivity: Tests connection to the RAG service
• Container health: Docker HEALTHCHECK integration

You can check system health by asking the agent: "Check system health" during a conversation.

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 OPENAI_API_KEY or your other LLM provider 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.

License

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