McDonald's Drive-Thru Voice AI Agent

A specialized voice AI agent built with LiveKit Agents for Python and LiveKit Cloud. This McDonald's Drive-Thru Agent takes customer orders using real menu data and natural language processing.

Overview

This repository demonstrates how to build a specialized voice AI agent using LiveKit. The Drive-Thru Agent (src/agent.py) handles customer orders with menu validation, item search, and order tracking capabilities.

Quick Start

Prerequisites

Python 3.11 or later
uv package manager
LiveKit Cloud account (free tier available)
API keys for:
- OpenAI (for LLM)
- AssemblyAI (for STT)
- Cartesia (for TTS)

Installation

Clone the repository and install dependencies:

git clone <repository-url>
cd lk-agent-1
uv sync

IMPORTANT: This project uses uv for dependency management. Always use uv run to execute commands (e.g., uv run python src/agent.py). Do not manually activate virtual environments - uv run handles this automatically.

Environment Setup

Sign up for LiveKit Cloud
Copy the example environment file:
```
cp .env.example .env.local
```
Fill in the required keys in .env.local:
- LIVEKIT_URL
- LIVEKIT_API_KEY
- LIVEKIT_API_SECRET
- OPENAI_API_KEY
- ASSEMBLYAI_API_KEY
- CARTESIA_API_KEY

You can also use the LiveKit CLI to automatically load environment variables:

lk cloud auth
lk app env -w -d .env.local

Download Model Files

Before running the agent for the first time, download required models:

uv run python src/agent.py download-files

This automatically downloads files for all registered LiveKit plugins:

Silero VAD (Voice Activity Detection) model
Multilingual turn detector model
Any other plugin-required models

McDonald's Drive-Thru Agent

What It Does

The Drive-Thru Agent is a specialized voice AI that:

Takes customer orders for McDonald's menu items
Searches and validates items against a real McDonald's menu
Handles item modifiers (add-ons, substitutions)
Confirms each item as it's added
Reads back the complete order
Saves orders as JSON files for processing

How It Works

The Drive-Thru Agent consists of several components:

DriveThruAgent (src/drive_thru_agent.py)
- Orchestrates the ordering conversation
- Defines the agent's persona and instructions
- Manages order state via OrderStateManager
- Provides tools for adding/confirming orders
DriveThruLLM (src/drive_thru_llm.py)
- Wraps the base LLM (e.g., GPT-4)
- Intercepts chat requests to inject menu context
- Searches menu based on keywords in user messages
- Reduces hallucination by grounding LLM in actual menu items
MenuProvider (src/menu_provider.py)
- Loads McDonald's menu from JSON
- Provides search functionality
- Returns structured menu items (categories, modifiers)
OrderStateManager (src/order_state_manager.py)
- Tracks order items during conversation
- Saves completed orders to JSON files
- One instance per session

Running the Drive-Thru Agent

Console Mode (Testing)

Test the agent directly in your terminal using LiveKit's built-in console:

uv run python src/agent.py console

Console Options:

--text: Start in text mode instead of audio mode
--input-device DEVICE: Select specific input audio device
--output-device DEVICE: Select specific output audio device
--list-devices: Show all available audio devices
--record: Record the session to disk

Examples:

# Text-based chat mode (no audio)
uv run python src/agent.py console --text

# List available audio devices
uv run python src/agent.py console --list-devices

# Use specific microphone
uv run python src/agent.py console --input-device "USB Microphone"

# Record the session
uv run python src/agent.py console --record

Interactive Features:

Press Ctrl+T during a session to toggle between audio and text modes
In audio mode, see real-time frequency visualization of your microphone input
Automatic device selection if not specified

This mode is perfect for:

Quick testing and debugging
Trying out the ordering flow
Experimenting with menu items
Testing without a frontend application

Dev Mode (LiveKit Connection)

Run the agent with a LiveKit connection for testing with real voice:

uv run python src/agent.py dev

This mode:

Connects to LiveKit Cloud
Supports frontend applications
Includes noise cancellation
Enables real voice interactions

Production Mode

For production deployment:

uv run python src/agent.py start

This is the production-ready entry point used in Docker deployments.

Menu Data

The McDonald's menu is stored as structured Pydantic models in menus/mcdonalds/:

Menu Structure - transformed-data/menu-structure-2026-01-21.json
Pydantic Models - models.py
- Menu - Complete menu with categories
- Item - Individual menu item with modifiers
- Modifier - Item variations (e.g., "Extra Cheese", "No Pickles")

Categories include:

Breakfast
Beef & Pork
Chicken & Fish
Snacks & Sides
Beverages
Coffee & Tea
Desserts
Smoothies & Shakes

Order Output

Completed orders are saved to the orders/ directory as JSON files:

{
  "session_id": "abc123",
  "items": [
    {
      "item_name": "Big Mac",
      "category": "Beef & Pork",
      "modifiers": ["Extra Cheese", "No Pickles"]
    }
  ],
  "timestamp": "2026-01-22T10:30:00Z"
}

Development

Project Structure

src/
├── agent.py                  # Drive-Thru Agent CLI (main entry point)
├── config.py                 # Pydantic configuration models
├── factories.py              # Creates STT/LLM/TTS instances
├── session_handler.py        # Session orchestration
├── drive_thru_agent.py       # Drive-Thru Agent implementation
├── drive_thru_llm.py         # Menu-aware LLM wrapper
├── menu_provider.py          # Menu search and loading
├── order_state_manager.py   # Order tracking
└── tools/
    └── order_tools.py        # Order management tools

menus/mcdonalds/
├── models.py                 # Pydantic menu models
├── transformed-data/         # Menu JSON files
└── raw-data/                 # Original menu data

tests/
├── conftest.py              # Shared pytest fixtures
├── test_drive_thru_agent.py # Agent tests
├── test_menu_models.py      # Menu model tests
└── ...

Testing

Run all tests:

uv run pytest

Run specific test file:

uv run pytest tests/test_drive_thru_agent.py -v

Run with coverage:

uv run pytest --cov=src --cov-report=html

Code Formatting

Format code with ruff:

uv run ruff format

Lint code:

uv run ruff check

Fix linting issues:

uv run ruff check --fix

Using the Makefile

This project includes a Makefile for common tasks:

make help           # Show all available commands
make console        # Run drive-thru agent in console mode
make dev            # Run drive-thru agent in dev mode
make test           # Run all tests
make format         # Format code
make lint           # Lint code
make download-files # Download model files

Plan Review Command

Review implementation plans for quality and executability before execution:

# Review a plan file
/review_plan plan/2026-01-23-feature-name.md

# Review a multi-file plan
/review_plan plan/2026-01-23-feature-name/

# Interactive mode
/review_plan

The review agent analyzes plans across 5 dimensions:

Accuracy - Technical correctness and validity
Consistency - Internal consistency and conventions
Clarity - Clear, unambiguous instructions
Completeness - All necessary steps and context
Executability - Can agents execute without intervention?

Output: Review saved to *.REVIEW.md with executability score (0-100) and detailed recommendations.

Note: Reviews are advisory only. No changes are made to original plans.

Architecture

Dependency Injection

This codebase uses dependency injection (DI) to construct components:

Configuration - src/config.py (Pydantic v2 models, env-driven)
Construction - src/factories.py (builds STT/LLM/TTS)
Wiring - src/agent.py (creates app + server)
Runtime - src/session_handler.py (manages sessions)

No custom adapters or protocols are used - components are constructed directly using LiveKit's concrete types.

Pydantic Models

This project uses Pydantic v2 for all data models:

Runtime validation
JSON serialization/deserialization
Schema generation
Environment variable integration
Better IDE support

See AGENTS.md for detailed guidelines on when to use Pydantic vs dataclasses.

Frontend & Deployment

Frontend Options

Get started with pre-built frontend applications:

Platform	Repository	Description
Web	`agent-starter-react`	React & Next.js web app
iOS/macOS	`agent-starter-swift`	Native iOS, macOS, visionOS
Flutter	`agent-starter-flutter`	Cross-platform mobile
React Native	`voice-assistant-react-native`	React Native & Expo
Android	`agent-starter-android`	Native Android (Kotlin)
Web Embed	`agent-starter-embed`	Embeddable widget
Telephony	Documentation	Phone integration

See the complete frontend guide for advanced customization.

Production Deployment

This project includes a production-ready Dockerfile. To deploy:

Build the Docker image:

docker build --platform linux/amd64 --no-cache -t drive-thru-agent .

Deploy to LiveKit Cloud or your preferred platform

See the deploying to production guide for details.

Coding Agents and MCP

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

Install the LiveKit Docs MCP server for best results:

For Cursor:

For Claude Code:

claude mcp add --transport http livekit-docs https://docs.livekit.io/mcp

For Codex CLI:

codex mcp add --url https://docs.livekit.io/mcp livekit-docs

For Gemini CLI:

gemini mcp add --transport http livekit-docs https://docs.livekit.io/mcp

The project includes a complete AGENTS.md file with coding guidelines. See https://agents.md to learn more.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 55 Commits
.claude		.claude
.github/assets		.github/assets
audio-samples		audio-samples
docs/python/references		docs/python/references
orders		orders
plan		plan
src		src
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
git-contributions-analysis.md		git-contributions-analysis.md
livekit.toml		livekit.toml
parse_menu.py		parse_menu.py
pyproject.toml		pyproject.toml
taskfile.yaml		taskfile.yaml
uv.lock		uv.lock

License

seanreed1111/lk-vanilla-mcdonalds-agent-with-toolcalls

Folders and files

Latest commit

History

Repository files navigation

McDonald's Drive-Thru Voice AI Agent

Table of Contents

Overview

Quick Start

Prerequisites

Installation

Environment Setup

Download Model Files

McDonald's Drive-Thru Agent

What It Does

How It Works

Running the Drive-Thru Agent

Console Mode (Testing)

Dev Mode (LiveKit Connection)

Production Mode

Menu Data

Order Output

Development

Project Structure

Testing

Code Formatting

Using the Makefile

Plan Review Command

Architecture

Dependency Injection

Pydantic Models

Frontend & Deployment

Frontend Options

Production Deployment

Coding Agents and MCP

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 2

Uh oh!

Languages

Packages