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
• 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.

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 your needs. To learn more about this file, see https://agents.md.

Clone the repository and install dependencies into your environment:

cd agent-starter-python
uv sync

If you want to interact with LiveKit Cloud from your terminal, install the lk CLI. On Linux this is a simple download + chmod:

# download the latest Linux binary and install to /usr/local/bin
curl -sSL https://github.com/livekit/cli/releases/latest/download/lk-linux-amd64 -o /usr/local/bin/lk
chmod +x /usr/local/bin/lk

# verify installation
lk --version

1. Create an account (or sign in) at: https://cloud.livekit.io/
2. Create an Application / API key pair in the LiveKit Cloud dashboard. Note down the LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET values.
3. Copy the example env file and add your keys:

cp .env.example .env.local
# Edit .env.local and set LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET

You can also use the LiveKit CLI to authenticate and write environment values (optional):

# open a browser and authenticate with LiveKit Cloud
lk cloud auth

# write environment variables to .env.local interactively (will prompt)
lk app env -w -d .env.local

Alternatively you can export the variables directly in your shell for a single run:

export LIVEKIT_URL="https://your-instance.livekit.cloud"
export LIVEKIT_API_KEY="<your_api_key>"
export LIVEKIT_API_SECRET="<your_api_secret>"

Start the agent in console mode to verify it can connect to LiveKit Cloud. With .env.local configured, run:

uv run python src/agent.py console

If you set env vars in the shell instead, run:

LIVEKIT_URL="$LIVEKIT_URL" LIVEKIT_API_KEY="$LIVEKIT_API_KEY" LIVEKIT_API_SECRET="$LIVEKIT_API_SECRET" uv run python src/agent.py console

Watch the agent logs — a successful connection will show the agent authenticating with LiveKit and registering any configured plugins. If you prefer to use the CLI to inspect LiveKit state, use the lk commands after a successful lk cloud auth.

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

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

For advanced customization, see the complete frontend guide.

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

uv run pytest

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.

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.

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.

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