LiveKit AI Agents

This repository contains two LiveKit voice AI agents demonstrating different capabilities and integrations.

Overview

• basic_livekit_agent.py - A Valorant-themed voice agent with function tools for match searching and scrim booking
• mcp_livekit_agent.py - An advanced voice agent with MCP (Model Context Protocol) server integration

Prerequisites

Required API Keys

Create a .env file in the project root with the following environment variables:

# OpenAI API Key (required for both agents)
OPENAI_API_KEY=your_openai_api_key_here

# Deepgram API Key (required for both agents)
DEEPGRAM_API_KEY=your_deepgram_api_key_here

# LiveKit credentials (get from your LiveKit Cloud dashboard)
LIVEKIT_URL=your_livekit_url_here
LIVEKIT_API_KEY=your_livekit_api_key_here
LIVEKIT_API_SECRET=your_livekit_api_secret_here

# Optional: LLM model choice (defaults to gpt-4.1-mini for MCP agent)
LLM_CHOICE=gpt-4.1-mini

Python Environment

# Install dependencies
pip install -r requirements.txt

# Or using uv (recommended)
uv sync

Agent 1: Basic Valorant Voice Agent

The basic agent demonstrates:

• Voice interaction with function tools
• Match searching by map
• Scrim booking functionality
• Simple conversational AI

Running the Basic Agent

uv run basic_livekit_agent.py console

Features

• Match Search: "Show me matches on Ascent"
• Join Scrims: "I want to join match asc001 as Phoenix, I'm a Duelist"
• Time Queries: "What time is it?"

Agent 2: MCP LiveKit Agent

The MCP agent demonstrates:

• Integration with external MCP servers
• Enhanced tool capabilities through Model Context Protocol
• Advanced voice pipeline configuration
• Real-time transcription

Prerequisites for MCP Agent

CRITICAL: Before running the MCP LiveKit agent, you must start the Docker MCP gateway:

docker mcp gateway --transport=streaming --port=80

This command starts the MCP gateway that the agent connects to at http://localhost:80/mcp.

Running the MCP Agent

uv run mcp_livekit_agent.py console

Features

• MCP Server Integration: Connects to external MCP servers for enhanced capabilities
• Advanced Voice Pipeline: Uses Deepgram Nova-2 STT and OpenAI TTS with Echo voice
• Transcription: Real-time conversation transcription
• Enhanced Instructions: Specialized for Airbnb MCP server tool usage (ignores robots.txt)

Architecture

Basic Agent Architecture

User Voice Input → Deepgram STT → OpenAI LLM → Function Tools → OpenAI TTS → Voice Output

MCP Agent Architecture

User Voice Input → Deepgram STT → OpenAI LLM → MCP Servers → Function Tools → OpenAI TTS → Voice Output

Configuration Options

Voice Pipeline Settings

Both agents support the following configurations:

• STT: Deepgram Nova-2 model
• LLM: OpenAI GPT models (configurable via LLM_CHOICE env var)
• TTS: OpenAI TTS with various voices
• VAD: Silero Voice Activity Detection

MCP Server Configuration

The MCP agent connects to MCP servers via HTTP at:

mcp_servers=[mcp.MCPServerHTTP(url="http://localhost:80/mcp")]

Troubleshooting

Common Issues

1. MCP Gateway Connection Failed

   • Ensure Docker MCP gateway is running: docker mcp gateway --transport=streaming --port=80
   • Check that port 80 is available and not blocked

2. API Key Errors

   • Verify all API keys are correctly set in .env
   • Check API key permissions and quotas

3. Voice Pipeline Issues

   • Ensure microphone permissions are granted
   • Test with different voice models if audio quality is poor

Logging

Both agents include comprehensive logging. Set log level via:

logging.basicConfig(level=logging.INFO)  # or DEBUG for verbose output

Development

Adding New Function Tools

Add new tools by decorating methods with @function_tool:

@function_tool
async def my_new_tool(self, context: RunContext, param: str) -> str:
    """Tool description for the LLM."""
    # Implementation here
    return "Tool result"

MCP Server Integration

To add new MCP servers, update the mcp_servers list in the agent configuration:

mcp_servers=[
    mcp.MCPServerHTTP(url="http://localhost:80/mcp"),
    # Add additional MCP servers here
]

License

This project is provided as an example implementation for LiveKit voice agents.