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

# build a voice agent with livekit

> a complete, from-scratch walkthrough: a real-time livekit voice agent that talks back in hinglish.

by the end you'll have a voice agent you can talk to, that replies out loud in
natural hinglish using rumik. we'll build it with
[livekit agents](https://docs.livekit.io/agents/), which gives you rooms, web and
mobile SDKs, and phone calls out of the box.

## what you'll build

a real-time loop running inside a livekit room: you speak, the agent transcribes
you, an LLM writes a reply, and silk speaks it back.

```
🎙️ you speak  →  STT (deepgram)  →  LLM (openai)  →  rumik TTS  →  🔊 it speaks
```

silk is the voice. you can swap the STT and LLM for any provider livekit supports.

## before you start

you need:

* **python 3.10+** and a terminal.
* a free **livekit cloud** project from [cloud.livekit.io](https://cloud.livekit.io)
  (gives you a URL, API key, and secret).
* three more API keys:
  * **rumik** for the voice, from [your dashboard](https://playground.rumik.ai/api-keys).
  * **deepgram** for speech-to-text ([deepgram.com](https://deepgram.com)).
  * **openai** for the LLM ([platform.openai.com](https://platform.openai.com)).

<Note>
  you can swap deepgram or openai for any STT / LLM that livekit supports. we use
  these two because they're quick to set up.
</Note>

## step 1 · set up the project

make a folder, a virtual environment, and install the packages.

```bash theme={null}
mkdir rumik-livekit-agent && cd rumik-livekit-agent
python -m venv venv
source venv/bin/activate        # windows: venv\Scripts\activate

pip install "livekit-agents[deepgram,openai,silero]" livekit-plugins-rumik-ai
```

`livekit-plugins-rumik-ai` is the official rumik TTS plugin.

## step 2 · add your keys

create a file called `.env`:

```bash .env theme={null}
LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=•••••••••
LIVEKIT_API_SECRET=•••••••••
RUMIK_API_KEY=rk_live_•••••••••
DEEPGRAM_API_KEY=•••••••••
OPENAI_API_KEY=sk-•••••••••
```

the livekit values come from your livekit cloud project settings.

## step 3 · write the agent

create `agent.py`. livekit wires the four steps together in an `AgentSession`. the
rumik part is the `tts` line.

```python agent.py theme={null}
from dotenv import load_dotenv

from livekit.agents import Agent, AgentSession, JobContext, WorkerOptions, cli
from livekit.plugins import deepgram, openai, silero, rumik_ai

load_dotenv()

# muga is steered by a [tone] tag, so we tell the LLM to add one
INSTRUCTIONS = """
You write text spoken by the Silk Muga 1 text-to-speech model.

- Output only the final tagged text, no markdown or notes.
- Romanised Hinglish only (Latin script). Never Devanagari.
- Start every reply with one tone tag, as the first token:
  [happy], [excited], [sad], [angry], [neutral], [whisper].
- Keep replies short: 1 to 2 sentences.
"""


async def entrypoint(ctx: JobContext):
    await ctx.connect()

    session = AgentSession(
        stt=deepgram.STT(),
        llm=openai.LLM(model="gpt-4o-mini"),
        tts=rumik_ai.TTS(model="muga"),   # the rumik voice
        vad=silero.VAD.load(),            # detects when you start/stop talking
    )

    await session.start(
        agent=Agent(instructions=INSTRUCTIONS),
        room=ctx.room,
    )


if __name__ == "__main__":
    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))
```

`rumik_ai.TTS` reads `RUMIK_API_KEY` from the environment automatically. the system
prompt makes the LLM emit muga's `[tone]` tags. the full rules are in
[prompting muga](/prompting-muga).

<Note>
  **tones are required — but there's a default.** muga speaks one `[tone]` per
  line, and the `INSTRUCTIONS` above make the LLM tag every reply. if a reply ever
  arrives without a tag, the plugin falls back to `[neutral]` so it never errors —
  or set your own fallback with `rumik_ai.TTS(model="muga", tone="happy")`.
</Note>

## step 4 · run it

start the agent worker:

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

then open the [livekit agents playground](https://agents-playground.livekit.io),
connect to your project, and talk. you'll hear muga reply in hinglish. it streams,
and livekit handles interruptions and turn-taking for you.

## customize it

<CardGroup cols={2}>
  <Card title="change the voice" icon="microphone-lines">
    use `rumik_ai.TTS(model="mulberry", description="...")` to design any voice. see
    [prompting mulberry](/prompting-mulberry).
  </Card>

  <Card title="pin a preset voice" icon="user-lock">
    add `speaker="ira"` alongside your `description` to pin one of the twelve
    named voices for the whole conversation.
  </Card>

  <Card title="tune the personality" icon="sliders">
    edit the `INSTRUCTIONS` system prompt. that's the agent's character.
  </Card>

  <Card title="set a default tone" icon="tags">
    `rumik_ai.TTS(model="muga", tone="neutral")` prefixes any untagged reply with
    that tone, so the LLM doesn't have to tag every line.
  </Card>

  <Card title="ship to phone or web" icon="phone">
    livekit handles telephony and web/mobile SDKs from the same agent.
  </Card>
</CardGroup>

## next steps

* [livekit integration reference](/livekit) for every constructor option.
* [prompting muga](/prompting-muga) and [prompting mulberry](/prompting-mulberry).
* prefer pipecat? build the [same agent with pipecat](/cookbook/voice-agent-pipecat).