## Get Your Voice Agent Up and Running

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](https://github.com/uplift-initiative/livekit-demo)

## 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 Pakistans 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:

- “قائد اعظم کے بارے میں بتائیں”
- “پاکستان کب بنا تھا؟”
- “موہنجو داڑو کیا ہے؟”

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