tutorials

Get your voice agent up and running in just a few simple steps.

This guide will help you build a voice assistant that teaches Pakistan history in Urdu.

Complete Demo Code

Get all files from GitHub

Quick Download

git clone https://github.com/uplift-initiative/livekit-demo
cd livekit-demo

Prerequisites

Step 1: Install Everything

Run this single command to install all dependencies:

pip install "livekit-agents==1.5.1" "livekit-plugins-openai==1.5.1" "livekit-plugins-turn-detector==1.5.1" "livekit-plugins-upliftai==1.5.1" "livekit-plugins-silero==1.5.1" "python-socketio[asyncio]>=5.11.0" "aiohttp>=3.9.0" "python-dotenv>=1.0.0" "loguru>=0.7.0" "openai>=1.84.0"

Step 2: Set Up Environment Variables

Create a .env file in your project folder:

OPENAI_API_KEY=your_openai_api_key_here
UPLIFTAI_API_KEY=your_uplift_api_key_here

Replace your_openai_api_key_here and your_uplift_api_key_here with your actual API keys.

Step 3: Create Your Voice Agent

Create a file named agent.py with this code:

from dotenv import load_dotenv
load_dotenv()

from livekit import agents
from livekit.agents import AgentSession, Agent, RoomInputOptions
from livekit.plugins import (
    openai,
    upliftai,
    silero,
)
from livekit.plugins.turn_detector.multilingual import MultilingualModel

class Assistant(Agent):
    def __init__(self) -> None:
        super().__init__(instructions="""
# Pakistan History Voice Assistant

## Core Identity
You are a knowledgeable Pakistani, who answers questions about Pakistan's history. You are a teacher who speaks in conversational Urdu.

## Language Rules
- Use Pakistani Urdu only (proper Urdu script, no Roman Urdu)
- Female perspective (میں بتاتی ہوں، سناتی ہوں، میری رائے میں)
- Gender-neutral for user (آپ جانتے ہوں گے، آپ کو یاد ہوگا)
- Simple, conversational language that anyone can understand
- Avoid English except for widely known terms (Congress, etc.)

## Response Style
- Tell history like stories, not dry facts
- Keep responses concise (2-3 sentences unless asked for detail)
- Use vivid descriptions to make history come alive
- Be balanced and factual about sensitive topics
- Write as continuous oral narration - no symbols or bullet points
- For dates: "انیس سو سینتالیس" not "1947"
                        ")

async def entrypoint(ctx: agents.JobContext):

tts = upliftai.TTS(
        voice_id="v_meklc281",
        output_format="MP3_22050_32",
    )

session = AgentSession(
        stt=openai.STT(model="gpt-4o-transcribe", language="ur"),
        llm=openai.LLM(model="gpt-4o-mini"),
        tts=tts,
        vad=silero.VAD.load(),
    )

await session.start(
        room=ctx.room,
        agent=Assistant(),
        room_input_options=RoomInputOptions(),
    )

await session.generate_reply(
        instructions="Greet the user and offer your assistance."
    )

if __name__ == "__main__":
    import os

agents.cli.run_app(agents.WorkerOptions(
        entrypoint_fnc=entrypoint,
        initialize_process_timeout=60,
    ))

Step 4: Verify Your Setup

Before proceeding, make sure your project directory looks like this:

your-project-folder/
├── .env                 # Your API keys
└── agent.py             # The voice agent code

All three files should be in the same folder!

Step 5: Download Required Files

Run this command to download necessary model files:

python agent.py download-files

Step 6: Run Your Agent!

You have two ways to test your agent:

Option A: Console Mode (Talk Directly)

python agent.py console

This lets you talk to your agent directly in the terminal!

Option B: Web Interface

python agent.py dev

Then open your browser to the URL shown in the terminal.

For the web interface, you’ll need LiveKit credentials. You can get free test credentials at livekit.io.

That’s It!

Your Pakistan History voice assistant is now running! Try asking questions like:

Additional Resources

Troubleshooting

ImportError: No module named 'livekit' Make sure you’ve installed all dependencies with the pip command in Step 1.

API Key Errors Double-check your .env file has the correct API keys without quotes.

Connection Failed Ensure your internet connection is stable and the API endpoints are accessible.