Agent Alex

AI voice assistant that makes real phone calls on your behalf. Talk to Alex, tell it who to call and what to say, and it handles the entire conversation for you.

Live at: https://www.agentalex.ai/

Features

• Voice Conversations: Chat with AI using WebRTC voice
• Outbound Phone Calls: AI agent calls businesses and contacts
• Web Search: Find businesses with addresses and phone numbers
• Call Transcripts: Full conversation history and summaries
• Mobile-First UI: ChatGPT-style interface that works on any device
• Usage Tracking: Authentication with usage limits and tracking
• MCP Integration: Knowledge tools via Model Context Protocol

Architecture

Browser (WebRTC) <-> Next.js App <-> Twilio Bridge <-> OpenAI Realtime API
                        |                |
                        v                v
                   Tavily Search      OpenAI Agents SDK
                        |                |
                        v                v
                   Supabase Auth    MCP Tools (deepwiki)

Quick Start

1. Clone and Install

git clone <repository-url>
cd web-agent
npm install

2. Configure Environment

Create .env.local:

# OpenAI (required)
OPENAI_API_KEY=sk-...

# Supabase (required for authentication and usage tracking)
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

# Twilio Bridge (required for phone calls)
BRIDGE_SECRET=your-strong-secret-here
TWILIO_BRIDGE_URL=https://your-bridge-domain.com

# Search (optional - enables web search)
SEARCH_PROVIDER=tavily
TAVILY_API_KEY=tvly-...

# Supervisor Model (optional)
SUPERVISOR_MODEL=gpt-4.1

3. Set Up Twilio Bridge

The bridge service handles phone calls:

cd services/twilio-bridge
npm install
cp .env.example .env  # Configure Twilio credentials
npm start

The bridge service is deployed on Railway. See services/twilio-bridge/README.md for configuration details.

4. Deploy to Production

The app is deployed automatically:

• Push changes to GitHub main branch
• Vercel automatically builds and deploys the Next.js app
• Railway automatically deploys the bridge service

Your app is available at https://www.agentalex.ai/. Click "Connect" to start talking.

Usage

• Voice Chat: Click "Connect" and speak naturally
• Make Calls: Say "Call [business]" or "Call +1234567890"
• Web Search: Say "Find pizza places near me"
• Ask Questions: Say "What is [topic]" to use MCP knowledge tools
• Complex Planning: Say "Help me plan..." to use supervisor tool
• Authentication: Enter email for magic link authentication to get extended usage
• Usage Tracking: Monitor your voice time usage in the bottom-left display

Project Structure

• src/app/ - Next.js app with API routes and components
• src/app/tools/ - Realtime agent tools (webSearch, phoneCall, supervisor)
• src/lib/calls/ - Phone call management and registry
• src/lib/search/ - Web search integration
• src/lib/supabase.ts - Authentication and usage tracking
• src/contexts/ - React contexts for events and transcripts
• services/twilio-bridge/ - Separate Node.js service for Twilio

Development Workflow

All development happens through GitHub commits and automated deployments:

1. Make changes locally - Edit files in your code editor
2. Commit to GitHub - Push changes to main branch
3. Automatic deployment - Vercel and Railway deploy within minutes
4. Test in production - Access the live app at https://www.agentalex.ai/

No local development servers or build commands needed.

Deployment

• Main App: Deployed on Vercel at https://www.agentalex.ai/
• Twilio Bridge: Deployed on Railway (WebSocket support required)
• Database: Supabase for authentication and usage tracking

See CLAUDE.md for deployment management commands.

License

MIT