LiveKit Agents Examples in Python

Runnable examples for building voice, video, and telephony agents using LiveKit Agents

This repository contains everything you need to learn and build production-ready voice AI agents using LiveKit Agents. From single-file quickstarts to multi-agent orchestration systems with companion frontends, these examples demonstrate real-world patterns and best practices.

python-agents-examples/
├── docs/examples/          # 50+ focused, single-concept demos
└── complex-agents/         # 20+ production-style applications with frontends

Every example includes YAML frontmatter metadata (title, category, tags, difficulty, description) for easy discovery by both humans and tooling.

# Clone the repository
git clone https://github.com/livekit-examples/python-agents-examples.git
cd python-agents-examples

# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Create a .env file in the repository root:

# Required - LiveKit credentials
LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=your_api_key
LIVEKIT_API_SECRET=your_api_secret

# Provider keys (add as needed for specific examples)
OPENAI_API_KEY=sk-...
DEEPGRAM_API_KEY=...
CARTESIA_API_KEY=...
ELEVENLABS_API_KEY=...
ANTHROPIC_API_KEY=...

# Start an interactive voice session
python docs/examples/listen_and_respond/listen_and_respond.py console

The console argument opens an interactive terminal session where you can speak or type with the agent.

Start here to understand core agent concepts.

Build complex workflows with multiple specialized agents.

Voice AI for phone systems.

Intercept and modify the STT → LLM → TTS pipeline.

Agents that can see.

Bring your agent to life with animated avatars.

Break language barriers.

Monitor and debug your agents.

React to conversation events and manage state.

Connect to external services.

These full-stack applications include both backend agents and React frontends.

Voice-driven D&D RPG with narrator/combat agents, character progression, and turn-based combat.

cd complex-agents/role-playing
python agent.py dev

# In another terminal
cd role_playing_frontend && pnpm install && pnpm dev

Features: Multi-agent switching, dice mechanics, NPC generation, inventory system, combat AI

Phone booking system with background observer agent and task groups.

cd complex-agents/doheny-surf-desk
python agent.py dev

Features: 5 specialized agents, LLM-based guardrails, sequential tasks, context injection

Voice-controlled research agent using EXA for web intelligence.

cd complex-agents/exa-deep-researcher
python agent.py dev

# In another terminal  
cd frontend && pnpm install && pnpm dev

Features: Background research jobs, RPC streaming, cited reports

Multi-department medical system with agent transfers.

cd complex-agents/medical_office_triage
python triage.py dev

Features: Triage → Specialist routing, chat history preservation, YAML prompts

Fast food ordering system with menu management.

cd complex-agents/drive-thru/drive-thru-agent
python agent.py dev

# In another terminal
cd ../frontend && pnpm install && pnpm dev

Job application interview with AWS Realtime.

cd complex-agents/nova-sonic
python form_agent.py dev

# In another terminal
cd nova-sonic-form-agent && pnpm install && pnpm dev

Features: AWS Realtime model, structured data collection, live form updates

Examples demonstrate integration with these providers:

The complete catalog lives in docs/index.yaml with metadata for every example:

- file_path: docs/examples/tool_calling/tool_calling.py
  title: Tool Calling
  category: basics
  tags: [tool-calling, deepgram, openai, cartesia]
  difficulty: beginner
  description: Shows how to use tool calling in an agent.
  demonstrates:
    - Using the most basic form of tool calling

# Find all telephony examples
rg "tags:.*telephony" docs/index.yaml

# Find all advanced examples  
rg "difficulty: advanced" docs/index.yaml

Every Python example starts with YAML frontmatter:

# Find examples using specific providers
rg "tags:.*elevenlabs" -g "*.py"

The repository includes testing utilities in complex-agents/testing/:

# Basic greeting test
async def test_agent_greeting():
    session = await create_test_session()
    response = await session.generate_reply()
    assert "hello" in response.lower()

Run tests with pytest:

cd complex-agents/testing
pytest -v

We welcome contributions! Please open an issue or PR if you:

• Find a bug or have a suggestion
• Want to add a new example
• Improve documentation

_{Built with ❤️ by the LiveKit team}