Voice Agent Starter — Powered by Murf Falcon

Build a production voice AI agent in 5 minutes. Powered by the fastest TTS on the market - swap the system prompt to build anything from customer support to language tutors.

---

Why Murf Falcon

• 55ms model latency - fastest production TTS
• 130ms time-to-first-audio across 10+ global regions
• $0.01/1000 characters - up to 10x cheaper than alternatives
• 150+ voices across 35+ languages
• 99.38% pronunciation accuracy

---

Architecture

flowchart LR
    A[🎙️ User speaks] -->|audio| B[Deepgram STT]
    B -->|text| C[LLM]
    C -->|response text| D[Murf Falcon TTS]
    D -->|audio| E[LiveKit]
    E -->|stream| F[🔊 User hears]

    style A fill:#444441,stroke:#888780,color:#fff
    style B fill:#185FA5,stroke:#85B7EB,color:#fff
    style C fill:#534AB7,stroke:#AFA9EC,color:#fff
    style D fill:#0F6E56,stroke:#5DCAA5,color:#fff
    style E fill:#D85A30,stroke:#F0997B,color:#fff
    style F fill:#444441,stroke:#888780,color:#fff

Loading

---

Quickstart

Prerequisites

• Python 3.10+
• uv - fast Python package manager

  # macOS/Linux
  curl -LsSf https://astral.sh/uv/install.sh | sh
  # Windows (PowerShell)
  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

• Node.js 18+
• pnpm — fast Node package manager

  npm install -g pnpm

• A LiveKit project (free tier available)

Step 1: Clone the repo

git clone https://github.com/murf-ai/murf-livekit-starter.git
cd murf-livekit-starter

Step 2: Set up environment variables

Create .env.local in both backend/ and frontend/ (copy from .env.example in each). You need:

Variable	Where to get it	Required
LIVEKIT_URL	LiveKit Cloud dashboard	Yes
LIVEKIT_API_KEY	LiveKit Cloud dashboard	Yes
LIVEKIT_API_SECRET	LiveKit Cloud dashboard	Yes
MURF_API_KEY	murf.ai/api/dashboard	Yes
DEEPGRAM_API_KEY	deepgram.com	Yes
GOOGLE_API_KEY (or OPENAI_API_KEY)	Depends on LLM choice	Yes

Step 3: Install backend dependencies

cd backend
uv sync
uv run python src/agent.py download-files

Step 4: Install frontend dependencies

cd frontend
pnpm install

Step 5: Run it

Option A - All-in-one (from repo root):

# macOS/Linux
chmod +x start_app.sh
./start_app.sh

# Windows (PowerShell)
.\start_app.ps1

Option B - Separate terminals:

# Terminal 1 — LiveKit Server
livekit-server --dev

# Terminal 2 — Backend agent
cd backend && uv run python src/agent.py dev

# Terminal 3 — Frontend
cd frontend && pnpm dev

Then open http://localhost:3000 in your browser.

You should now see the voice agent UI. Click Start talking, allow microphone access, and speak — the agent will respond with Murf Falcon TTS. Ensure your backend and (if using Option B) LiveKit server are running.

---

Deploy

Want to deploy this beyond localhost? You'll need to deploy two services: the backend agent and the frontend. Both must use the same LiveKit project.

This is a two-service app — the backend agent and the frontend UI deploy separately. You'll need both running and connected to the same LiveKit project.

Backend (Python agent) — Deploy to Railway

Set these environment variables in Railway:

• MURF_API_KEY
• DEEPGRAM_API_KEY
• GOOGLE_API_KEY or OPENAI_API_KEY
• LIVEKIT_URL
• LIVEKIT_API_KEY
• LIVEKIT_API_SECRET

The backend runs as a long-lived Python process that connects to LiveKit as an agent. Railway handles this well.

Frontend (Next.js) — Deploy to Vercel

Set these environment variables in Vercel:

• LIVEKIT_URL
• LIVEKIT_API_KEY
• LIVEKIT_API_SECRET
• AGENT_NAME (optional — for explicit agent dispatch)

The frontend is a standard Next.js app. Point it at the same LiveKit instance your backend agent is connected to.

Connecting them

The frontend and backend don't call each other directly — they both connect to LiveKit, which handles the real-time audio transport.

1. Use the same LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET on both Railway and Vercel
2. Set AGENT_NAME=my-agent on Vercel — this matches the agent_name="my-agent" registered in backend/src/agent.py
3. Verify: Railway logs should show the agent connected to LiveKit. Open your Vercel URL, click Start talking — the agent should respond

If the agent doesn't connect, double-check that both services point to the same LiveKit project and that the backend is running (check Railway logs).

---

Change the Use Case

The default system prompt makes this a customer support agent. You can change the agent’s behavior by editing the prompt.

Where the prompt lives: backend/src/agent.py- the SYSTEM_PROMPT constant (near the top of the file, after the imports). Change that string to change what your voice agent does.

Healthcare Facility Lookup (Day 5)

The "Aarogya Sahayak" agent includes a find_health_facilities voice tool: ask "Is there a PHC in Ranchi?" or "Find a government hospital near me" and the agent looks up real facilities and speaks them naturally.

• Data source: the public OpenStreetMap Overpass API — live at query time, no API key required.
• Data origin: community-maintained OpenStreetMap data (including government health facilities imported from data.gov.in). It is not government-verified and may be incomplete or outdated — the agent always says when the data was last refreshed.
• Failure behavior: service unavailable, timeouts, and invalid responses produce a graceful spoken fallback; the agent never invents facilities, names, phones, or addresses.
• Optional tuning: HEALTH_FACILITIES_TIMEOUT_S in backend/.env.local (default 10s per request).

Outbound Calling (Day 6)

The same "Aarogya Sahayak" agent can place an outbound healthcare follow-up call (appointment or medication reminder). A dialing utility (backend/src/telephony/outbound.py) creates a dedicated room, dials the destination through your LiveKit Cloud outbound SIP trunk (LIVEKIT_SIP_OUTBOUND_TRUNK_ID), dispatches the existing my-agent into the call, monitors it, and cleans the room up.

• One call per run only — no auto-redialing is implemented. The utility reports clear success/failure (no answer, busy, unavailable, rejected, immediate hang-up) and refuses invalid/missing numbers and configuration before dialing anything.
• The agent's outbound opening always states who is calling, why (scheduled follow-up/reminder), and how to end the call (say "end the call"/"stop" or hang up) — see OUTBOUND_OPENING in backend/src/prompt.py.
• All credentials and the trunk ID are read from backend/.env.local and never printed (the CLI's --dry-run prints only set/MISSING).
• One manual test call: start the agent (uv run python src/agent.py dev), then in another terminal:

  cd backend
  uv run python -m telephony.outbound '+919876543210'   # dial your own test number

• Run uv run python -m telephony.outbound --dry-run first to verify configuration without dialing.
• Safety/consent: only dial numbers you are authorised to call; the callee must be told who is calling and why, and opt-out ("don't call me again") must be honoured instantly. See backend/README.md → "Outbound Calling (Day 6)" for the full matrix and setup.

Example prompts (copy-paste)

Customer Support (default):

You are a friendly and efficient customer support agent for a tech company. Help users with account issues, billing questions, and product troubleshooting. Be concise, empathetic, and solution-oriented. If you don't know something, say so honestly and offer to escalate.

Language Tutor:

You are a patient and encouraging language tutor helping the user practice conversational Spanish. Speak primarily in Spanish but switch to English to explain grammar or vocabulary when needed. Correct mistakes gently and suggest better phrasing. Keep conversations natural and fun.

AI Receptionist:

You are a professional receptionist for a medical clinic. Help callers schedule appointments, answer questions about office hours and services, and take messages for doctors. Be warm but efficient. Ask for the caller's name and reason for calling upfront.

See the Configuration section below for voice, STT, and LLM options.

---

Configuration

Murf voice

Edit the tts=murf.TTS(...) call in backend/src/agent.py. Set the voice argument to any Murf voice ID. Examples:

• Anisha — Indian English (female, default in this starter)
• Pooja — Indian English (female)
• Samar — Indian English (male)
• Amara — US English (female)
• Gordon — US English (male)
• Hazel — UK English (female)
• Bertie — UK English (male)

Browse all voices: Murf Voice Library.

STT provider

STT is configured in backend/src/agent.py in the AgentSession(stt=...) call. The default is Deepgram (deepgram.STT(model="nova-3")). You can swap to another LiveKit-compatible STT plugin if needed.

LLM (Gemini vs OpenAI)

• Gemini (default): Set GOOGLE_API_KEY and use llm=google.LLM(model="gemini-3.5-flash-lite") in agent.py.
• OpenAI: Set OPENAI_API_KEY, add the OpenAI plugin, and use the corresponding llm=openai.LLM(...) in agent.py.

Audio format

Murf Falcon and LiveKit handle audio format internally. For advanced options, see Murf API docs and LiveKit docs.

---

Project Structure

murf-livekit-starter/
├── backend/                 # Python voice agent (LiveKit Agents + Murf Falcon)
│   ├── src/
│   │   ├── agent.py         # Agent entrypoint, pipeline (STT/LLM/TTS), system prompt
│   │   ├── prompt.py        # Aarogya Sahayak prompt + Day 6 outbound opening
│   │   ├── memory.py        # Day 4: caller memory store
│   │   ├── health_facilities.py  # Day 5: facility lookup
│   │   └── telephony/
│   │       └── outbound.py  # Day 6: outbound dialing utility + CLI
│   ├── tests/               # Agent tests (Days 4-6)
│   ├── .env.example         # Backend env template
│   ├── pyproject.toml       # Python deps (uv)
│   └── railway.toml         # Railway deploy config
├── frontend/                # Next.js UI for voice sessions
│   ├── app/
│   │   ├── page.tsx         # Main page
│   │   └── api/token/       # LiveKit token endpoint (dev)
│   ├── components/          # UI (agents-ui, app config, theme)
│   ├── app-config.ts        # Branding, title, button text, accent
│   ├── .env.example         # Frontend env template
│   └── package.json         # Node deps (pnpm)
├── start_app.sh             # Start LiveKit + backend + frontend (macOS/Linux)
├── start_app.ps1            # Start LiveKit + backend + frontend (Windows)
├── README.md                # This file

For deeper documentation on each part, see:

• Backend Documentation — agent pipeline, voice/LLM/STT configuration, testing, deployment
• Frontend Documentation — UI customization, visualizers, theming, component architecture

---

Links

• Murf API Docs
• Murf Voice Library
• LiveKit Docs
• Deepgram Docs
• Murf Falcon Benchmarks
• TTS Latency Benchmarker — run your own p50/p95 tests across providers
• Murf Discord
• Murf Startup Incubator — 50M free characters for startups

---

License

MIT