LiveKit Agents starter for Python

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

The starter includes:

• A simple voice AI assistant to extend and customize.
• A voice pipeline built on LiveKit Inference, which gives you access to models from top labs with no extra configuration:
  • The default LLM is Gemma 4 31B, an open-weight model hosted by LiveKit and tuned for voice AI.
  • The default TTS is Fish Audio S2.1 Pro, an expressive and cost-effective voice.
  • More than 50 other models are available from OpenAI, Cartesia, Deepgram, and other providers.
  • Realtime models and many others are available through the plugin ecosystem.
• Expressive mode, on by default, so your agent's voice carries emotion and pacing that fit the conversation.
• Keyterms, on by default, so speech recognition gets your names, brands, and jargon right, including names it picks up during the conversation, like a caller's.
• LiveKit Turn Detector, which knows when the user has finished speaking, in 14 languages.
• Adaptive interruption handling, which tells a real interruption from an "uh-huh" or background noise, so your agent doesn't stop talking when it shouldn't.
• Background voice cancellation.
• Session transcripts, traces, and recordings from LiveKit Agent Observability.
• Simulations that test full conversations with your agent, run in CI on every merge to main.
• A Dockerfile for deploying to LiveKit Cloud.

The starter works with any custom web or mobile frontend or with telephony.

Using coding agents

This project works with coding agents like Claude Code, Cursor, and Codex.

LiveKit offers both a CLI and an MCP server for browsing and searching its documentation. Search returns short excerpts, so fetch the full page to read the details:

lk docs search "testing my agent"
lk docs get-page /testing/unit-tests

The project also includes an AGENTS.md file and LiveKit's agent skills, so your coding agent follows LiveKit's best practices for workflows, handoffs, and testing, and tries its changes with the agent debugger. See the coding agents guide for more details, including MCP server setup and how to update the skill.

Dev setup

Install the LiveKit CLI, version 2.18.8 or later:

• macOS: brew install livekit-cli
• Linux: curl -sSL https://get.livekit.io/cli | bash
• Windows: winget install LiveKit.LiveKitCLI

Check your version with lk --version. To update an existing install, see Update the CLI.

Then create a project from this template. The CLI clones the template and configures your environment:

lk cloud auth
lk agent init my-agent --template agent-starter-python

Set up the project manually

Clone the repository and install dependencies into a virtual environment with uv:

git clone https://github.com/livekit-examples/agent-starter-python.git
cd agent-starter-python
uv sync

Sign up for LiveKit Cloud, then copy .env.example to .env.local and fill it in. To have the CLI write your project's URL and API keys into the file instead, run:

lk cloud auth
lk app env --write --destination .env.local

Run the agent

The lk agent console, lk agent dev, and lk agent debugger commands run your agent on your own machine. To talk to it in your terminal:

lk agent console

To connect it to LiveKit Cloud so a frontend, a phone call, or the Agent Console can reach it:

lk agent dev

To let a coding agent or a script test it one text turn at a time, use the agent debugger. Each turn prints the agent's reply along with the tool calls and handoffs behind it:

lk agent debugger start
lk agent debugger say "Hi, what can you do?"
lk agent debugger stop

In production, run the agent directly:

uv run src/agent.py start

Frontends and telephony

Pair the agent with a prebuilt frontend starter, or add telephony:

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 more options, see the frontend guide.

Testing and debugging

Simulations run full multi-turn conversations between a simulated user and your agent on LiveKit Cloud, then judge each transcript. The scenarios live in scenarios.yaml. Run them locally with the CLI:

lk agent simulate text --scenarios scenarios.yaml

The Simulations workflow in .github/workflows/simulations.yml runs the same file on every merge to main, and on demand from the Actions tab. It doesn't run on every pull request push because each run uses real inference. See the simulations guide for how to write scenarios and read results.

To check a change turn by turn without a live session, use the agent debugger shown in Run the agent.

To debug a running agent, open it in the Agent Console. It shows events, tool calls, and model timing as you talk to the agent. To stream logs from a deployed agent, run lk agent logs.

Using this template for your own project

After you create your own project from this template:

• Commit uv.lock. The template doesn't track it, but your project should, for reproducible builds. If you deploy to LiveKit Cloud, commit livekit.toml too.
• Add repository secrets. Add LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET as repository secrets so the simulations can run in CI.

Deploying to production

To deploy the agent to LiveKit Cloud or another environment with the included Dockerfile, see the deployment guide.

Self-hosted LiveKit

You can self-host LiveKit instead of using LiveKit Cloud. See the self-hosting guide. If you self-host, use model plugins instead of LiveKit Inference, and remove the LiveKit Cloud noise cancellation plugin.

License

This project is licensed under the MIT License. See LICENSE for details.