LangGraph Voice Call Agent

A real-time voice/call AI agent that lets you talk to a LangGraph agent over LiveKit, similar to "voice mode" experiences in ChatGPT Voice, OpenAI Realtime API sessions, and Gemini Live. This repo demonstrates adapting any LangGraph agent into a full-duplex, low-latency voice assistant using LiveKit's real-time communication infrastructure.

This backend provides the core voice processing and AI agent functionality, built to work seamlessly with LiveKit's real-time infra and any frontend that supports LiveKit client connections.

Features

• Real-time voice interaction with LangGraph agents
• Full-duplex communication with low-latency audio processing
• Flexible LangGraph integration - works with any LangGraph agent
• Comprehensive audio pipeline including VAD, STT, TTS, and turn detection
• Thread-based conversation continuity via participant metadata

Project Structure

langgraph-voice-call-agent/
├── src/                         # Main source code
│   ├── livekit/                 # LiveKit agent implementation
│   │   ├── agent.py             # Main agent entrypoint
│   │   └── adapter/             # LangGraph integration
│   │       └── langgraph.py     # LangGraph adapter for LiveKit
│   └── langgraph/               # LangGraph Agent Sdefinitions
│       └── agent.py             # An example agent
├── compose.yml                  # Docker Compose for local LiveKit server
├── pyproject.toml               # Python project configuration
├── uv.lock                      # uv dependency lock file
└── Makefile                     # Development commands

How it works (high level)

1. Agent Initialization → LiveKit agent connects to room and waits for participants
2. Audio Pipeline Setup → VAD, STT, TTS, and turn detection models are loaded and configured
3. LangGraph Integration → Connect to LangGraph server
4. Voice Processing → Real-time audio is processed through the pipeline:
   • Voice Activity Detection (VAD) detects when user speaks
   • Speech-to-Text (STT) transcribes audio to text
   • LangGraph agent processes the query and generates responses
   • Text-to-Speech (TTS) converts responses back to audio
   • Turn detection manages conversation flow
5. Thread Continuity → Conversation state is maintained via thread IDs from participant metadata

Architecture

• Backend: Python with LiveKit Agents and LangGraph
• Voice Infrastructure: LiveKit's real-time infra
• AI Agents: LangGraph agents
• Audio Pipeline: Deepgram STT/TTS, Silero VAD, English turn detection
• State Management: Thread-based conversation continuity

Quick Start

Prerequisites

• Python 3.12+ with uv package manager
• Docker & Docker Compose for local LiveKit server
• LiveKit Cloud account (optional, for cloud deployment)

Installation

1. Clone and setup the project:

git clone https://github.com/ahmad2b/langgraph-voice-call-agent.git
cd langgraph-voice-call-agent

# Initialize with uv
uv sync

2. Download required model files:

make download-files
# or
uv run -m src.livekit.agent download-files

3. Start local LiveKit server:

docker compose up -d

4. Run the agent:

make dev
# or
uv run -m src.livekit.agent dev

Development Setup

Using uv (Recommended)

This project uses uv for fast Python package management:

# Install dependencies
uv sync

# Add new dependencies
uv add package-name

# Add dev dependencies
uv add --dev package-name

# Run commands
uv run -m src.livekit.agent dev
uv run -m src.livekit.agent download-files

Local Development

Local LiveKit Server

The compose.yml provides a local LiveKit server for development:

# Key configuration:
- Port 7880: API and WebSocket
- Port 7881: TURN/TLS
- Port 7882: UDP for media
- Development keys: "devkey: secret"

Start local server:

docker compose up -d

Check server status:

docker compose ps
docker compose logs livekit

LangGraph Dev Server (Required)

Run the LangGraph API server locally so the LiveKit agent can call your graph via RemoteGraph.

# Python CLI (default port 2024)
uv run langgraph dev

Set the LangGraph server URL (optional; defaults to http://localhost:2024):

# .env
LANGGRAPH_URL=http://localhost:2024

The agent reads LANGGRAPH_URL and falls back to http://localhost:2024 if not set.

Environment Variables

Create .env file for local development:

# LiveKit Local Server
LIVEKIT_URL=ws://localhost:7880
LIVEKIT_API_KEY=devkey
LIVEKIT_API_SECRET=secret

# OpenAI (for LangGraph agent)
OPENAI_API_KEY=your-openai-key

# Deepgram (for STT/TTS)
DEEPGRAM_API_KEY=your-deepgram-key

# LangGraph dev server (optional; default http://localhost:2024)
LANGGRAPH_URL=http://localhost:2024

LiveKit Cloud Deployment

For production use, deploy to LiveKit Cloud for better performance and features.

1. Get LiveKit Cloud Credentials

1. Sign up at LiveKit Cloud
2. Create a new project
3. Get your API keys from the project dashboard

2. Update Environment Variables

# LiveKit Cloud
LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=your-api-key
LIVEKIT_API_SECRET=your-api-secret

3. Update Agent Configuration

Modify src/livekit/agent.py to use cloud URL:

# For cloud deployment, remove local server setup
# The agent will connect to LiveKit Cloud automatically

File Descriptions

Core Files

• src/livekit/agent.py: Main LiveKit agent entrypoint

  • Connects to LiveKit room
  • Manages participant sessions
  • Integrates VAD, STT, LLM, TTS, and turn detection
  • Extracts threadId from participant metadata for conversation continuity

• src/livekit/adapter/langgraph.py: LangGraph integration adapter

  • Bridges LiveKit LLM interface to LangGraph workflows
  • Handles streaming responses (messages and custom modes)
  • Converts LangGraph outputs to LiveKit ChatChunks

• src/langgraph/agent.py: Todo management agent

  • Defines ReAct agent with todo tools
  • Handles add, list, complete, and delete operations
  • Supports user confirmation for deletions

Configuration Files

• compose.yml: Local LiveKit server setup
• pyproject.toml: Python project configuration
• Makefile: Development commands and shortcuts

Testing the Agent

Frontend

LangGraph Voice Call Agent Web

Using the LangGraph Voice Call Agent Web

1. Start this backend (see Quick Start above)
2. Clone and run the frontend:

   git clone https://github.com/ahmad2b/langgraph-voice-call-agent-web.git
   cd langgraph-voice-call-agent-web
   npm install && npm run dev

3. Open http://localhost:3000

Connection Details

• Local: ws://localhost:7880
• Cloud: wss://your-project.livekit.cloud
• Room: Auto-generated room names
• Authentication: API key/secret or JWT tokens

Troubleshooting

Common Issues

1. Model Download Issues

VAD and turn detection models need downloading before first use.

Error symptoms:

FileNotFoundError: Model files not found

Solution:

make download-files
# or directly
uv run -m src.livekit.agent download-files

2. Port Conflicts

LiveKit ports already in use.

Solution:

docker compose ps
docker compose down  # Stop existing containers
docker compose up -d

3. Import Errors

Module not found errors.

Solution: Always use the module format:

# ✅ Correct
uv run -m src.livekit.agent dev

# ❌ Incorrect  
python src/livekit/agent.py

4. LangGraph Connection Issues

Agent can't connect to LangGraph server.

Error symptoms:

Connection refused to localhost:2024

Solution:

# Ensure LangGraph server is running
uv run langgraph dev

# Or run both together
make dev-all

5. Environment Variable Issues

Missing or incorrect API keys.

Solution: Create .env file with all required variables:

cp .env.example .env  # If available
# Then edit .env with your actual keys

Getting Help

If you continue experiencing issues:

1. Check logs for specific error messages
2. Verify system requirements (Python 3.12+)
3. Test with minimal setup (local LiveKit server first)
4. Check LiveKit Cloud status if using cloud deployment

References

• LiveKit Agents Documentation
• LiveKit Self-Hosting Guide
• LiveKit Cloud Documentation
• LangGraph Documentation

Contributing

This project is open source and welcome contributions! Please open a PR or issue through GitHub.

This project demonstrates LiveKit + LangGraph integration patterns. Feel free to:

• Report issues and bugs
• Suggest improvements and new features
• Submit pull requests
• Use as a reference for your own voice agent projects
• Share your own LangGraph agent implementations

Connect

I'm actively exploring voice-first and real-time agents. If you're building in this space or experimenting with real-time AI infrastructure, I'd love to trade ideas, collaborate, or help out.

• GitHub: ahmad2b
• Twitter/X: @mahmad2b
• LinkedIn: Ahmad Shaukat
• Book a chat: cal.com/mahmad2b/15min

License

MIT License - see LICENSE file for details.

Acknowledgments

Inspired by dqbd/langgraph-livekit-agents.