LiveKit Agent

A voice AI project built with LiveKit Agents for Python and LiveKit Cloud. This project is designed to work with coding agents like Claude Code, Cursor, and Codex — see Coding agent support for setup tips.

Important

This project was converted to code from the LiveKit Agent Builder. The code is identical to production deployments from the builder. Follow the steps below to make it your own and deploy it to LiveKit Cloud. once you do so, you can delete the version in the builder.

Next steps

Run and deploy your agent

Get your agent running locally and in production:

1. Run locally: Follow the Quickstart section below to set up your environment and test the agent
2. Deploy to production: See the Deploy to production section for deployment options and best practices

Quickstart

Get up and running so you can start customizing:

1. Install dependencies:

   uv sync

2. Set up your LiveKit credentials:

   Sign up for LiveKit Cloud, then configure your environment. You can either:

   • Manual setup: Copy .env.example to .env.local and fill in:

     • LIVEKIT_URL
     • LIVEKIT_API_KEY
     • LIVEKIT_API_SECRET

   • Automatic setup (recommended): Use the LiveKit CLI:

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

3. Download required models:

   uv run python src/agent.py download-files

   This downloads Silero VAD and the LiveKit turn detector models.

4. Test your agent:

   uv run python src/agent.py console

   This lets you speak to your agent directly in your terminal.

5. Run for development:

   uv run python src/agent.py dev

   Use this when connecting to a frontend or telephony. This puts your agent into your LiveKit Cloud project, so use a different project if you don't want to affect production traffic.

Customize your agent

Once your agent is running, enhance it for your use case:

• Customize AI models: Your agent uses a voice AI pipeline built on LiveKit Inference. More than 50 model providers are supported, including Realtime models.

• Add tests: You can add a full test suite to your agent. See the testing documentation for more information.

• Build reliable workflows: For complex agents, use tasks and handoffs instead of long instruction prompts. This minimizes latency and improves reliability by structuring your agent into focused, reusable components.

Get help from AI coding assistants

Supercharge your development with AI coding assistants that understand LiveKit. This project works seamlessly with Claude Code, Cursor, Codex, and other AI coding tools.

For your convenience, LiveKit offers both a CLI and an MCP server that can be used to browse and search its documentation. The LiveKit CLI (lk docs) works with any coding agent that can run shell commands. Install it for your platform:

macOS:

brew install livekit-cli

Linux:

curl -sSL https://get.livekit.io/cli | bash

Windows:

winget install LiveKit.LiveKitCLI

The lk docs subcommand requires version 2.15.0 or higher. Check your version with lk --version and update if needed. Once installed, your coding agent can search and browse LiveKit documentation directly from the terminal:

lk docs search "voice agents"
lk docs get-page /agents/start/voice-ai-quickstart

See the Using coding agents guide for more details, including MCP server setup.

Customize the AI assistant context: The project includes an AGENTS.md file that guides AI assistants on how to work with this codebase. Edit this file to add your own project-specific context, patterns, and preferences. Learn more at https://agents.md.

Frontend development

If you don't alread have a frontend, use the following templates and guides to get started on one:

Platform	Starter Template	What to customize
Web	livekit-examples/agent-starter-react	React & Next.js—customize UI, add features, integrate with your backend
iOS/macOS	livekit-examples/agent-starter-swift	Native apps for iOS, macOS, visionOS—add platform-specific features
Flutter	livekit-examples/agent-starter-flutter	Cross-platform—customize for Android, iOS, web, desktop
React Native	livekit-examples/voice-assistant-react-native	Mobile with Expo—add native modules, customize navigation
Android	livekit-examples/agent-starter-android	Kotlin & Jetpack Compose—build Material Design UI
Web Embed	livekit-examples/agent-starter-embed	Widget for any website—customize styling, add to your site
Telephony	Documentation	Add phone calling—configure SIP, add call routing, customize prompts

Observability

LiveKit provides deep session insights for your agents through Agent Observability. Monitor conversation quality, track latency metrics, and debug agent behavior in production.

Deploy to production

To deploy your agent to production, you can use the LiveKit CLI:

lk agent create

See the deploying to production guide for detailed instructions and optimization tips.

Google credentials for STT/TTS fallback

Do not copy key.json into the Docker image. LiveKit Cloud supports file-mounted secrets and mounts them under /etc/secrets/<filename> at runtime. This project sets GOOGLE_APPLICATION_CREDENTIALS=/etc/secrets/key.json in the Dockerfile.

For an existing LiveKit Cloud agent, mount the local service account file and set the matching environment variable:

./scripts/mount_google_credentials.sh ./key.json

You can also pass the same secret mount when deploying a new image:

lk agent deploy \
  --secret-mount ./key.json \
  --secrets "GOOGLE_APPLICATION_CREDENTIALS=/etc/secrets/key.json"

For local Docker runs, mount the file read-only at the same path:

docker run --rm \
  -v "$PWD/key.json:/etc/secrets/key.json:ro" \
  your-agent-image

Join the LiveKit community

Join the LiveKit Slack Community to get help from the LiveKit team and other developers.