> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upliftai.org/llms.txt
> Use this file to discover all available pages before exploring further.

# LiveKit Voice Agent

> Build a Pakistan History voice assistant in 5 minutes

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.

<CardGroup cols={2}>
  <Card title="Complete Demo Code" icon="github" href="https://github.com/uplift-initiative/livekit-demo">
    Get all files from GitHub
  </Card>

  <Card title="Quick Download" icon="download" color="#16A34A">
    ```bash theme={null}
    git clone https://github.com/uplift-initiative/livekit-demo
    cd livekit-demo
    ```
  </Card>
</CardGroup>

## Prerequisites

* Python 3.9 or higher
* An Uplift AI API key ([Get one here](https://upliftai.org))
* An OpenAI API key ([Get one here](https://platform.openai.com))

## Step 1: Install Everything

Run this single command to install all dependencies:

```bash theme={null}
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:

```bash theme={null}
OPENAI_API_KEY=your_openai_api_key_here
UPLIFTAI_API_KEY=your_uplift_api_key_here
```

<Note>
  Replace `your_openai_api_key_here` and `your_uplift_api_key_here` with your actual API keys.
</Note>

## Step 3: Create Your Voice Agent

Create a file named `agent.py` with this code:

```python theme={null}
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
```

<Check>
  All three files should be in the same folder!
</Check>

## Step 5: Download Required Files

Run this command to download necessary model files:

```bash theme={null}
python agent.py download-files
```

## Step 6: Run Your Agent!

You have two ways to test your agent:

### Option A: Console Mode (Talk Directly)

```bash theme={null}
python agent.py console
```

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

### Option B: Web Interface

```bash theme={null}
python agent.py dev
```

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

<Tip>
  For the web interface, you'll need LiveKit credentials. You can get free test credentials at [livekit.io](https://livekit.io).
</Tip>

## 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](/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

<AccordionGroup>
  <Accordion title="ImportError: No module named 'livekit'">
    Make sure you've installed all dependencies with the pip command in Step 1.
  </Accordion>

  <Accordion title="API Key Errors">
    Double-check your `.env` file has the correct API keys without quotes.
  </Accordion>

  <Accordion title="Connection Failed">
    Ensure your internet connection is stable and the API endpoints are accessible.
  </Accordion>
</AccordionGroup>

***

<Card title="Get Complete Demo" icon="github" href="https://github.com/uplift-initiative/livekit-demo">
  View the full working example with all files on GitHub
</Card>