## 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
- Python 3.9 or higher
- An Uplift AI API key ( [Get one here](/content/site-root.html))
- An OpenAI API key ( [Get one here](https://platform.openai.com/))

## 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](https://livekit.io/).

## That’s It!
Your Pakistan History voice assistant is now running! Try asking questions like:
- “قائد اعظم کے بارے میں بتائیں”
- “پاکستان کب بنا تھا؟”
- “موہنجو داڑو کیا ہے؟”

## Additional Resources
- [Complete Demo Repository](https://github.com/uplift-initiative/livekit-demo) - Full working example with all files
- [LiveKit Documentation](https://docs.livekit.io/) - Learn more about LiveKit
- [Uplift AI API Reference](https://docs.upliftai.org/introduction) - Explore more TTS options
- [OpenAI API Documentation](https://platform.openai.com/docs) - OpenAI models and features
- [LiveKit Python SDK](https://github.com/livekit/python-sdks) - Python SDK reference

## 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.