Production-ready voice AI agent template.
Retell AI + MCP + Twilio. Clone, configure, deploy in 5 minutes.

---

What This Is

A complete starter template for building production voice AI agents. Not a demo. Not a tutorial. A real, deployable system with:

• Retell AI for voice agent orchestration
• MCP (Model Context Protocol) for tool connectivity
• Twilio for telephony (inbound + outbound calls)
• Pre-built tools: CRM lookup, calendar booking, knowledge base Q&A
• 4 industry examples: dental receptionist, med spa booking, customer support, sales qualifier

Clone → Add API keys → Deploy → Answer calls

---

Architecture

graph TD
    Phone[📞 Incoming Call] --> Twilio[Twilio SIP]
    Twilio --> Retell[Retell AI Agent]
    Retell --> STT[Speech-to-Text]
    STT --> LLM[LLM Processing<br/>GPT-4o / Claude]
    LLM --> Tools{MCP Tool Calls}
    Tools --> CRM[CRM Lookup<br/>HubSpot / Salesforce]
    Tools --> Calendar[Calendar Booking<br/>Google Calendar]
    Tools --> KB[Knowledge Base<br/>RAG / FAQ]
    Tools --> Custom[Your Custom Tools]
    LLM --> TTS[Text-to-Speech<br/>ElevenLabs / Deepgram]
    TTS --> Retell
    Retell --> Twilio
    Twilio --> Phone

    style Retell fill:#FF9900,stroke:#333,color:#fff
    style LLM fill:#4A90D9,stroke:#333,color:#fff
    style Tools fill:#28a745,stroke:#333,color:#fff

Loading

---

Quick Start

Prerequisites

• Node.js 18+
• Retell AI account (free tier available)
• Twilio account (for phone numbers)
• API key for an LLM (OpenAI or Anthropic)

1. Clone and Install

git clone https://github.com/ALLBOTSIO/voice-agent-starter.git
cd voice-agent-starter
npm install
cp .env.example .env

2. Configure

Edit .env with your API keys:

RETELL_API_KEY=your_retell_key
TWILIO_ACCOUNT_SID=your_twilio_sid
TWILIO_AUTH_TOKEN=your_twilio_token
TWILIO_PHONE_NUMBER=+1234567890
OPENAI_API_KEY=your_openai_key        # or ANTHROPIC_API_KEY
HUBSPOT_API_KEY=your_hubspot_key      # optional: CRM integration
GOOGLE_CALENDAR_CREDENTIALS=./creds.json  # optional: calendar booking

3. Choose an Example Agent

# Dental receptionist
npm run start:dental

# Med spa booking agent
npm run start:medspa

# Customer support agent
npm run start:support

# Sales lead qualifier
npm run start:sales

# Custom agent
npm run dev

4. Deploy

# Railway (recommended)
railway deploy

# Docker
docker compose up -d

# Manual
npm run build && npm start

---

Project Structure

voice-agent-starter/
├── agent/
│   ├── index.ts              # Main agent configuration
│   ├── retell-config.ts      # Retell AI setup and webhook handler
│   ├── mcp-bridge.ts         # MCP server connector
│   ├── tools/
│   │   ├── crm-lookup.ts     # HubSpot/Salesforce contact lookup
│   │   ├── calendar.ts       # Google Calendar availability + booking
│   │   ├── knowledge-base.ts # RAG-powered FAQ answering
│   │   └── transfer.ts       # Call transfer to human agent
│   └── prompts/
│       ├── base-system.md    # Base system prompt (shared)
│       ├── dental.md         # Dental receptionist persona
│       ├── medspa.md         # Med spa booking persona
│       ├── support.md        # Customer support persona
│       └── sales.md          # Sales qualifier persona
├── mcp-servers/
│   ├── crm-lookup/           # MCP server: CRM contact search
│   ├── calendar/             # MCP server: Calendar booking
│   └── knowledge-base/       # MCP server: FAQ/RAG queries
├── examples/
│   ├── dental-receptionist/  # Full config for dental practice
│   ├── med-spa-booking/      # Full config for med spa
│   ├── customer-support/     # Full config for support center
│   └── sales-qualifier/      # Full config for sales team
├── deploy/
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── railway.toml
├── .env.example
├── package.json
├── tsconfig.json
└── README.md

---

Pre-Built Tools

CRM Lookup

Searches HubSpot or Salesforce for caller info by phone number. Agent greets callers by name and has full context.

// Automatically triggered on inbound call
const contact = await tools.crmLookup(callerPhoneNumber);
// Returns: { name, email, company, lastInteraction, openDeals }

Calendar Booking

Checks availability on Google Calendar and books appointments.

// "I'd like to book an appointment for next Tuesday"
const slots = await tools.getAvailability("2026-04-14");
const booking = await tools.bookAppointment(slot, contactInfo);

Knowledge Base

RAG-powered Q&A against your documents. Upload PDFs, markdown, or text files.

// "What are your pricing plans?"
const answer = await tools.queryKnowledgeBase("pricing plans");

Call Transfer

Transfer to a human agent with context.

// "Let me connect you with a specialist"
await tools.transferCall("+1555123456", { reason, context });

---

Industry Examples

Dental Receptionist

AI receptionist for dental practices. Books cleanings, handles insurance questions, routes emergencies.

Med Spa Booking

Handles Botox, fillers, and treatment consultations. Books appointments, explains procedures, sends confirmations.

Customer Support

Tier-1 support agent. Answers FAQs, creates tickets, escalates complex issues to humans.

Sales Qualifier

Qualifies inbound leads. Asks discovery questions, scores leads, books meetings with sales reps.

---

Adding Custom Tools

Create a new tool in agent/tools/:

// agent/tools/my-tool.ts
import { Tool } from '../types';

export const myTool: Tool = {
  name: 'my_custom_tool',
  description: 'What this tool does',
  parameters: {
    query: { type: 'string', description: 'Search query' }
  },
  handler: async ({ query }) => {
    // Your logic here
    return { result: 'data' };
  }
};

Register it in agent/index.ts and the agent can use it immediately.

---

Environment Variables

Variable	Required	Description
RETELL_API_KEY	Yes	Retell AI API key
TWILIO_ACCOUNT_SID	Yes	Twilio Account SID
TWILIO_AUTH_TOKEN	Yes	Twilio Auth Token
TWILIO_PHONE_NUMBER	Yes	Your Twilio phone number
OPENAI_API_KEY	Yes*	OpenAI API key (*or Anthropic)
ANTHROPIC_API_KEY	Yes*	Anthropic API key (*or OpenAI)
HUBSPOT_API_KEY	No	HubSpot CRM integration
GOOGLE_CALENDAR_CREDENTIALS	No	Path to Google Calendar service account JSON
KNOWLEDGE_BASE_PATH	No	Path to documents folder for RAG
WEBHOOK_SECRET	No	Retell webhook verification secret

---

Related Projects

• awesome-voice-ai — Curated list of 150+ voice AI tools
• Alexa-MCPs — 200 MCP servers for voice assistants
• mcp-marketplace — Open-source MCP server registry

---

License

MIT — AI Venture Holdings LLC

Built by ALLBOTS.io · A portfolio company of AI Venture Holdings LLC
_{⭐ Star this repo if you build something with it}