Skip to content
Public template

About

A complete voice AI starter for LiveKit Agents with Python.

Resources

Stars

274 stars

Watchers

5 watching

Forks

Repository files navigation

LiveKit logo

LiveKit Agents starter for Python

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

Getting started

  1. Install uv, which manages Python and the project's dependencies.

  2. Install the LiveKit CLI and sign in to LiveKit Cloud:

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

    Sign up for a free LiveKit Cloud account if you don't have one, then link it to the CLI:

    lk cloud auth
  3. Create your project from this starter:

    lk agent init my-agent --template agent-starter-python
  4. Talk to your agent. Run it in your terminal and speak into your microphone:

    cd my-agent
    lk agent console

    If you didn't let lk agent init install dependencies, run uv sync first.

What's included

The starter includes:

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

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 coding agents

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

Agent skills. Install LiveKit's agent skills, which teach your coding agent to build, debug, test, and deploy LiveKit agents:

lk skills install

To get the latest skills, run lk skills update.

AGENTS.md. Teaches your coding agent LiveKit's best practices for workflows, handoffs, and testing, and has it check its changes with the agent debugger.

For more, see the coding agents guide.

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.
  • Commit the agent skills and skills-lock.json, if you installed them in the project.
  • 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, see the deployment guide.

License

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

About

A complete voice AI starter for LiveKit Agents with Python.

Resources

Stars

274 stars

Watchers

5 watching

Forks

Used by

Contributors

Languages