{"id":30516808,"url":"https://github.com/ahmad2b/langgraph-voice-call-agent","last_synced_at":"2026-04-17T08:03:47.171Z","repository":{"id":311126105,"uuid":"1042525311","full_name":"ahmad2b/langgraph-voice-call-agent","owner":"ahmad2b","description":"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 Agents.","archived":false,"fork":false,"pushed_at":"2025-08-22T08:03:03.000Z","size":105,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-22T10:16:20.637Z","etag":null,"topics":["agents","call-agent","langgraph","livekit","realtime-chat","voice","voice-agent","voice-agents"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ahmad2b.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-22T06:45:14.000Z","updated_at":"2025-08-22T08:03:06.000Z","dependencies_parsed_at":"2025-08-22T10:16:29.136Z","dependency_job_id":"5b7f3e4b-b070-47e7-8f0e-7e7e1cc9bc99","html_url":"https://github.com/ahmad2b/langgraph-voice-call-agent","commit_stats":null,"previous_names":["ahmad2b/langgraph-voice-call-agent"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ahmad2b/langgraph-voice-call-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahmad2b%2Flanggraph-voice-call-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahmad2b%2Flanggraph-voice-call-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahmad2b%2Flanggraph-voice-call-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahmad2b%2Flanggraph-voice-call-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ahmad2b","download_url":"https://codeload.github.com/ahmad2b/langgraph-voice-call-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahmad2b%2Flanggraph-voice-call-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272207493,"owners_count":24891986,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-26T02:00:07.904Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","call-agent","langgraph","livekit","realtime-chat","voice","voice-agent","voice-agents"],"created_at":"2025-08-26T10:07:34.111Z","updated_at":"2026-04-17T08:03:47.160Z","avatar_url":"https://github.com/ahmad2b.png","language":"Python","funding_links":[],"categories":["Agent Categories"],"sub_categories":["\u003ca name=\"LangGraph\"\u003e\u003c/a\u003eLangGraph"],"readme":"# LangGraph Voice Call Agent\n\nA 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.\n\nThis 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.\n\n## Features\n\n- **Real-time voice interaction** with LangGraph agents\n- **Full-duplex communication** with low-latency audio processing\n- **Flexible LangGraph integration** - works with any LangGraph agent\n- **Comprehensive audio pipeline** including VAD, STT, TTS, and turn detection\n- **Thread-based conversation continuity** via participant metadata\n\n## Project Structure\n\n```\nlanggraph-voice-call-agent/\n├── src/                         # Main source code\n│   ├── livekit/                 # LiveKit agent implementation\n│   │   ├── agent.py             # Main agent entrypoint\n│   │   └── adapter/             # LangGraph integration\n│   │       └── langgraph.py     # LangGraph adapter for LiveKit\n│   └── langgraph/               # LangGraph Agent Sdefinitions\n│       └── agent.py             # An example agent\n├── compose.yml                  # Docker Compose for local LiveKit server\n├── pyproject.toml               # Python project configuration\n├── uv.lock                      # uv dependency lock file\n└── Makefile                     # Development commands\n```\n\n## How it works (high level)\n\n1. **Agent Initialization** → LiveKit agent connects to room and waits for participants\n2. **Audio Pipeline Setup** → VAD, STT, TTS, and turn detection models are loaded and configured  \n3. **LangGraph Integration** → Connect to LangGraph server\n4. **Voice Processing** → Real-time audio is processed through the pipeline:\n   - Voice Activity Detection (VAD) detects when user speaks\n   - Speech-to-Text (STT) transcribes audio to text\n   - LangGraph agent processes the query and generates responses\n   - Text-to-Speech (TTS) converts responses back to audio\n   - Turn detection manages conversation flow\n5. **Thread Continuity** → Conversation state is maintained via thread IDs from participant metadata\n\n## Architecture\n\n- **Backend**: Python with LiveKit Agents and LangGraph\n- **Voice Infrastructure**: LiveKit's real-time infra\n- **AI Agents**: LangGraph agents\n- **Audio Pipeline**: Deepgram STT/TTS, Silero VAD, English turn detection\n- **State Management**: Thread-based conversation continuity\n\n## Quick Start\n\n### Prerequisites\n\n- **Python 3.12+** with `uv` package manager\n- **Docker \u0026 Docker Compose** for local LiveKit server\n- **LiveKit Cloud account** (optional, for cloud deployment)\n\n### Installation\n\n1. **Clone and setup the project:**\n```bash\ngit clone https://github.com/ahmad2b/langgraph-voice-call-agent.git\ncd langgraph-voice-call-agent\n\n# Initialize with uv\nuv sync\n```\n\n2. **Download required model files:**\n```bash\nmake download-files\n# or\nuv run -m src.livekit.agent download-files\n```\n\n3. **Start local LiveKit server:**\n```bash\ndocker compose up -d\n```\n\n4. **Run the agent:**\n```bash\nmake dev\n# or\nuv run -m src.livekit.agent dev\n```\n\n## Development Setup\n\n### Using `uv` (Recommended)\n\nThis project uses `uv` for fast Python package management:\n\n```bash\n# Install dependencies\nuv sync\n\n# Add new dependencies\nuv add package-name\n\n# Add dev dependencies\nuv add --dev package-name\n\n# Run commands\nuv run -m src.livekit.agent dev\nuv run -m src.livekit.agent download-files\n```\n\n## Local Development\n\n### Local LiveKit Server\n\nThe `compose.yml` provides a local LiveKit server for development:\n\n```yaml\n# Key configuration:\n- Port 7880: API and WebSocket\n- Port 7881: TURN/TLS\n- Port 7882: UDP for media\n- Development keys: \"devkey: secret\"\n```\n\n**Start local server:**\n```bash\ndocker compose up -d\n```\n\n**Check server status:**\n```bash\ndocker compose ps\ndocker compose logs livekit\n```\n\n### LangGraph Dev Server (Required)\n\nRun the LangGraph API server locally so the LiveKit agent can call your graph via RemoteGraph.\n\n```bash\n# Python CLI (default port 2024)\nuv run langgraph dev\n```\n\nSet the LangGraph server URL (optional; defaults to http://localhost:2024):\n\n```bash\n# .env\nLANGGRAPH_URL=http://localhost:2024\n```\n\nThe agent reads `LANGGRAPH_URL` and falls back to `http://localhost:2024` if not set.\n\n### Environment Variables\n\nCreate `.env` file for local development:\n\n```bash\n# LiveKit Local Server\nLIVEKIT_URL=ws://localhost:7880\nLIVEKIT_API_KEY=devkey\nLIVEKIT_API_SECRET=secret\n\n# OpenAI (for LangGraph agent)\nOPENAI_API_KEY=your-openai-key\n\n# Deepgram (for STT/TTS)\nDEEPGRAM_API_KEY=your-deepgram-key\n\n# LangGraph dev server (optional; default http://localhost:2024)\nLANGGRAPH_URL=http://localhost:2024\n```\n\n## LiveKit Cloud Deployment\n\nFor production use, deploy to LiveKit Cloud for better performance and features.\n\n### 1. Get LiveKit Cloud Credentials\n\n1. Sign up at [LiveKit Cloud](https://cloud.livekit.io/)\n2. Create a new project\n3. Get your API keys from the project dashboard\n\n### 2. Update Environment Variables\n\n```bash\n# LiveKit Cloud\nLIVEKIT_URL=wss://your-project.livekit.cloud\nLIVEKIT_API_KEY=your-api-key\nLIVEKIT_API_SECRET=your-api-secret\n```\n\n### 3. Update Agent Configuration\n\nModify `src/livekit/agent.py` to use cloud URL:\n\n```python\n# For cloud deployment, remove local server setup\n# The agent will connect to LiveKit Cloud automatically\n```\n\n## File Descriptions\n\n### Core Files\n\n- **`src/livekit/agent.py`**: Main LiveKit agent entrypoint\n  - Connects to LiveKit room\n  - Manages participant sessions\n  - Integrates VAD, STT, LLM, TTS, and turn detection\n  - Extracts threadId from participant metadata for conversation continuity\n\n- **`src/livekit/adapter/langgraph.py`**: LangGraph integration adapter\n  - Bridges LiveKit LLM interface to LangGraph workflows\n  - Handles streaming responses (`messages` and `custom` modes)\n  - Converts LangGraph outputs to LiveKit ChatChunks\n\n- **`src/langgraph/agent.py`**: Todo management agent\n  - Defines ReAct agent with todo tools\n  - Handles add, list, complete, and delete operations\n  - Supports user confirmation for deletions\n\n### Configuration Files\n\n- **`compose.yml`**: Local LiveKit server setup\n- **`pyproject.toml`**: Python project configuration\n- **`Makefile`**: Development commands and shortcuts\n\n## Testing the Agent\n\n### Frontend\n\n[LangGraph Voice Call Agent Web](https://github.com/ahmad2b/langgraph-voice-call-agent-web)\n\n#### Using the [LangGraph Voice Call Agent Web](https://github.com/ahmad2b/langgraph-voice-call-agent-web)\n\n1. Start this backend (see Quick Start above)\n2. Clone and run the frontend:\n   ```bash\n   git clone https://github.com/ahmad2b/langgraph-voice-call-agent-web.git\n   cd langgraph-voice-call-agent-web\n   npm install \u0026\u0026 npm run dev\n   ```\n3. Open http://localhost:3000\n\n### Connection Details\n\n- **Local**: `ws://localhost:7880`\n- **Cloud**: `wss://your-project.livekit.cloud`\n- **Room**: Auto-generated room names\n- **Authentication**: API key/secret or JWT tokens\n\n## Troubleshooting\n\n### Common Issues\n\n#### 1. **Model Download Issues** \nVAD and turn detection models need downloading before first use.\n\n**Error symptoms:**\n```\nFileNotFoundError: Model files not found\n```\n\n**Solution:**\n```bash\nmake download-files\n# or directly\nuv run -m src.livekit.agent download-files\n```\n\n#### 2. **Port Conflicts**\nLiveKit ports already in use.\n\n**Solution:**\n```bash\ndocker compose ps\ndocker compose down  # Stop existing containers\ndocker compose up -d\n```\n\n#### 3. **Import Errors**\nModule not found errors.\n\n**Solution:**\nAlways use the module format:\n```bash\n# ✅ Correct\nuv run -m src.livekit.agent dev\n\n# ❌ Incorrect  \npython src/livekit/agent.py\n```\n\n#### 4. **LangGraph Connection Issues**\nAgent can't connect to LangGraph server.\n\n**Error symptoms:**\n```\nConnection refused to localhost:2024\n```\n\n**Solution:**\n```bash\n# Ensure LangGraph server is running\nuv run langgraph dev\n\n# Or run both together\nmake dev-all\n```\n\n#### 5. **Environment Variable Issues**\nMissing or incorrect API keys.\n\n**Solution:**\nCreate `.env` file with all required variables:\n```bash\ncp .env.example .env  # If available\n# Then edit .env with your actual keys\n```\n\n### Getting Help\n\nIf you continue experiencing issues:\n\n1. **Check logs** for specific error messages\n2. **Verify system requirements** (Python 3.12+)\n3. **Test with minimal setup** (local LiveKit server first)\n4. **Check LiveKit Cloud status** if using cloud deployment\n\n## References\n\n- [LiveKit Agents Documentation](https://github.com/livekit/agents)\n- [LiveKit Self-Hosting Guide](https://docs.livekit.io/home/self-hosting/)\n- [LiveKit Cloud Documentation](https://docs.livekit.io/home/cloud/)\n- [LangGraph Documentation](https://github.com/langchain-ai/langgraph)\n\n## Contributing\n\nThis project is open source and welcome contributions! Please open a PR or issue through GitHub.\n\nThis project demonstrates LiveKit + LangGraph integration patterns. Feel free to:\n\n- Report issues and bugs\n- Suggest improvements and new features\n- Submit pull requests\n- Use as a reference for your own voice agent projects\n- Share your own LangGraph agent implementations\n\n## Connect\n\nI'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.\n\n- GitHub: [ahmad2b](https://github.com/ahmad2b)  \n- Twitter/X: [@mahmad2b](https://x.com/mahmad2b)  \n- LinkedIn: [Ahmad Shaukat](https://www.linkedin.com/in/ahmad2b)  \n- Book a chat: [cal.com/mahmad2b/15min](https://cal.com/mahmad2b/15min)\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\nInspired by [dqbd/langgraph-livekit-agents](https://github.com/dqbd/langgraph-livekit-agents).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fahmad2b%2Flanggraph-voice-call-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fahmad2b%2Flanggraph-voice-call-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fahmad2b%2Flanggraph-voice-call-agent/lists"}