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

Overview

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.

Quick Start

Prerequisites

Installation

# 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

Environment Setup

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=...

Run Your First Agent

# 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.

Examples by Category

Fundamentals

Start here to understand core agent concepts.

Multi-Agent Systems

Build complex workflows with multiple specialized agents.

Telephony & SIP

Voice AI for phone systems.

Pipeline Customization

Intercept and modify the STT → LLM → TTS pipeline.

Vision & Multimodal

Agents that can see.

Avatars & Visual Agents

Bring your agent to life with animated avatars.

Translation & Multilingual

Break language barriers.

Metrics & Observability

Monitor and debug your agents.

Events & State

React to conversation events and manage state.

Advanced Integrations

Connect to external services.

Full Applications

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

🎮 Dungeons & Agents

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

📞 Doheny Surf Desk

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

🔬 EXA Deep Researcher

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

🏥 Medical Office Triage

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

🍔 Drive-Thru

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

📝 Nova Sonic Form Agent

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

Provider Support

Examples demonstrate integration with these providers:

Discovery Tools

Browse the Index

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 Examples by Tag

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

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

Frontmatter Search

Every Python example starts with YAML frontmatter:

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

Testing

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

Resources

Contributing

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}