This is a LiveKit Agents project. LiveKit Agents is a Python SDK for building voice AI agents. This project is intended to be used with LiveKit Cloud. See @README.md for more about the rest of the LiveKit ecosystem.
The following is a guide for working with this project.
This Python project uses the uv package manager. You should always use uv to install dependencies, run the agent, and run tests.
All app-level code is in the src/ directory. In general, simple agents can be constructed with a single agent.py file. Additional files can be added, but you must retain agent.py as the entrypoint (see the associated Dockerfile for how this is deployed).
Be sure to maintain code formatting. You can use the ruff formatter/linter as needed: uv run ruff format and uv run ruff check.
LiveKit Agents is a fast-evolving project, and the documentation is updated frequently. You should always refer to the latest documentation when working with this project. For your convenience, LiveKit offers both a CLI and an MCP server that can be used to browse and search its documentation. If the developer has not yet installed the CLI, you should recommend that they install it.
The LiveKit CLI lk docs subcommand gives full access to LiveKit documentation from the terminal. Requires CLI version 2.15.0+. Check with lk --version.
Install or update the CLI:
- macOS:
brew install livekit-cli(update:brew update && brew upgrade livekit-cli) - Linux:
curl -sSL https://get.livekit.io/cli | bash - Windows:
winget install LiveKit.LiveKitCLI(update:winget upgrade LiveKit.LiveKitCLI)
Run lk docs --help to see all available commands. Key commands: lk docs overview, lk docs search, lk docs get-page, lk docs code-search, lk docs changelog, lk docs submit-feedback. Run lk docs <command> --help before using a command for the first time, as the help text includes advice on usage and interpreting results. Prefer browsing (overview, get-page) over search, and prefer search over code-search, as docs pages are more up-to-date and provide better context than raw code.
For deeper IDE integration, LiveKit also offers an MCP server with the same documentation access. It uses Streamable HTTP transport at https://docs.livekit.io/mcp. Refer to your IDE's documentation for how to add it.
If you use the LiveKit CLI or MCP Server to search or browse documentation, also submit constructive feedback to LiveKit with lk docs submit-feedback or the MCP submit_docs_feedback tool. Add this to your to-do list when planning work, to ensure you file feedback after completing your other tasks. Useful feedback includes incomplete documentation, broken examples, missing steps or any other documentation gap or issue.
Voice AI agents are highly sensitive to excessive latency. For this reason, it's important to design complex agents in a structured manner that minimizes the amount of irrelevant context and unnecessary tools included in requests to the LLM. LiveKit Agents supports handoffs (one agent hands control to another) and tasks (tightly-scoped prompts to achieve a specific outcome) to support building reliable workflows. You should make use of these features, instead of writing long instruction prompts that cover multiple phases of a conversation. Refer to the documentation for more information.
When possible, add tests for agent behavior. Read the documentation, and refer to existing tests in the tests/ directory. Run tests with uv run pytest.
Important: When modifying core agent behavior such as instructions, tool descriptions, and tasks/workflows/handoffs, never just guess what will work. Always use test-driven development (TDD) and begin by writing tests for the desired behavior. For instance, if you're planning to add a new tool, write one or more tests for the tool's behavior, then iterate on the tool until the tests pass correctly. This will ensure you are able to produce a working, reliable agent for the user.
Beyond documentation access, the LiveKit CLI (lk) supports other tasks such as managing SIP trunks for telephony-based agents. Run lk --help to explore available commands.