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

# Voice agent

> Build a voice agent that listens with Prisma, answers with Evon and speaks with Timbre, using LiveKit or Pipecat.

Early access
**Gnani Evon v3.5** is now available as an API to early access registrants.

A voice agent runs three models in a loop: **Prisma** turns the caller's speech into text, **Evon** writes the reply, and **Timbre** speaks it. This recipe wires them together in LiveKit or Pipecat.

## When to use this

* You want a phone or web voice agent that speaks Indian languages.
* You already use LiveKit Agents or Pipecat, or want a framework to handle audio, turn-taking and interruptions.
* You want the reply to start playing before the whole answer is written.

***

## Check the LLM settings first

Before you build the agent, send one request with the settings a voice agent needs: thinking off, streaming on and short replies.

```bash cURL theme={null}
# -N shows each event as soon as it arrives
curl -N https://api.vachana.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-API-Key-ID: $GNANI_API_KEY" \
  -d '{
    "model": "evon-v3.5",
    "stream": true,
    "reasoning_effort": "none",
    "max_tokens": 150,
    "messages": [
      {"role": "system", "content": "You are an AI voice assistant for an online store. Reply in one or two short sentences, in the caller'\''s language. Do not use lists, markdown or emoji."},
      {"role": "user", "content": "मेरा ऑर्डर कब तक आएगा?"}
    ]
  }'
```

```python Python (OpenAI SDK) theme={null}
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.vachana.ai/v1",
    api_key=os.environ["GNANI_API_KEY"],
)

stream = client.chat.completions.create(
    model="evon-v3.5",
    messages=[
        {"role": "system", "content": "You are an AI voice assistant for an online store. Reply in one or two "
                                      "short sentences, in the caller's language. Do not use lists, markdown or emoji."},
        {"role": "user", "content": "मेरा ऑर्डर कब तक आएगा?"},
    ],
    stream=True,
    reasoning_effort="none",  # thinking off: the first word arrives sooner
    max_tokens=150,           # short spoken replies; see Limits for your plan's maximum
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
```

```javascript JavaScript (OpenAI SDK) theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.vachana.ai/v1",
  apiKey: process.env.GNANI_API_KEY,
});

const stream = await client.chat.completions.create({
  model: "evon-v3.5",
  messages: [
    {
      role: "system",
      content: "You are an AI voice assistant for an online store. Reply in one or two short sentences, in the caller's language. Do not use lists, markdown or emoji.",
    },
    { role: "user", content: "मेरा ऑर्डर कब तक आएगा?" },
  ],
  stream: true,
  reasoning_effort: "none", // thinking off: the first word arrives sooner
  max_tokens: 150, // short spoken replies; see Limits for your plan's maximum
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
```

```python Python (requests) theme={null}
import json
import os
import requests

with requests.post(
    "https://api.vachana.ai/v1/chat/completions",
    headers={"X-API-Key-ID": os.environ["GNANI_API_KEY"]},
    json={
        "model": "evon-v3.5",
        "stream": True,
        "reasoning_effort": "none",
        "max_tokens": 150,
        "messages": [
            {"role": "system", "content": "You are an AI voice assistant for an online store. Reply in one or two "
                                          "short sentences, in the caller's language. Do not use lists, markdown or emoji."},
            {"role": "user", "content": "मेरा ऑर्डर कब तक आएगा?"},
        ],
    },
    stream=True,
    timeout=300,
) as response:
    response.raise_for_status()
    for line in response.iter_lines(decode_unicode=True):
        if not line or not line.startswith("data: "):
            continue
        data = line[len("data: "):]
        if data == "[DONE]":
            break
        event = json.loads(data)
        if "error" in event:
            raise RuntimeError(event["error"]["message"])
        if event["choices"]:
            print(event["choices"][0]["delta"].get("content") or "", end="", flush=True)
```

The reply streams in a few pieces. Joined, it reads something like:

```text theme={null}
मैं आपकी मदद ज़रूर करूँगा। कृपया अपना ऑर्डर नंबर बताइए।
```

***

## Build the agent

The Gnani [LiveKit](https://docs.gnani.ai/livekit/introduction.md) and [Pipecat](https://docs.gnani.ai/pipecat/introduction.md) plugins provide speech-to-text and text-to-speech only. For the LLM, use each framework's **OpenAI plugin** with the Evon base URL. This works because the API is [OpenAI-compatible](https://docs.gnani.ai/api/LLM/openai-compatibility.md).

> [tab] LiveKit
>
> Install the packages:
>
> ```bash theme={null}
> pip install "livekit-agents[openai,silero]" livekit-plugins-gnani
> ```
>
> Set `GNANI_API_KEY`, plus `LIVEKIT_URL`, `LIVEKIT_API_KEY` and `LIVEKIT_API_SECRET` for your LiveKit project. Save this as `agent.py`:
>
> ```python agent.py highlight={18-24} theme={null}
> import os
>
> from livekit.agents import Agent, AgentSession, JobContext, WorkerOptions, cli
> from livekit.plugins import gnani, openai, silero
>
> INSTRUCTIONS = (
>     "You are an AI voice assistant for an online store. "
>     "Reply in one or two short sentences, in the caller's language. "
>     "Do not use lists, markdown or emoji, because your reply is spoken aloud."
> )
>
>
> async def entrypoint(ctx: JobContext):
>     await ctx.connect()
>
>     session = AgentSession(
>         stt=gnani.STT(model="prisma-v3.0", language=["hi-IN", "en-IN"]),
>         llm=openai.LLM(
>             model="evon-v3.5",
>             base_url="https://api.vachana.ai/v1",
>             api_key=os.environ["GNANI_API_KEY"],
>             reasoning_effort="none",    # thinking off: the first word arrives sooner
>             max_completion_tokens=150,  # short spoken replies; see Limits
>         ),
>         tts=gnani.TTS(
>             model="timbre-v3.0",
>             voice="Avinash",
>             language="hi-IN",
>             synthesize_method="websocket",
>         ),
>         vad=silero.VAD.load(),
>     )
>
>     await session.start(room=ctx.room, agent=Agent(instructions=INSTRUCTIONS))
>     await session.generate_reply(
>         instructions="Greet the caller in Hindi, say that you are an AI assistant, and ask how you can help."
>     )
>
>
> if __name__ == "__main__":
>     cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))
> ```
>
> Download the voice activity model once, then talk to the agent in your terminal:
>
> ```bash theme={null}
> python agent.py download-files
> python agent.py console
> ```
>
> Use `python agent.py dev` to connect it to your LiveKit project instead.

> [tab] Pipecat
>
> Start from the plugin's [foundational example](https://github.com/Gnani-AI-Mintlify/pipecat-gnani/blob/main/examples/foundational/agent.py), which sets up the transport. Install the OpenAI service too:
>
> ```bash theme={null}
> pip install pipecat-gnani "pipecat-ai[openai,silero]"
> ```
>
> Then replace the STT, TTS and Groq LLM services, and give the context a system message:
>
> ```python agent.py highlight={13-21} theme={null}
> import os
>
> from pipecat.processors.aggregators.llm_context import LLMContext
> from pipecat.services.openai.llm import OpenAILLMService
> from pipecat.transcriptions.language import Language
> from pipecat_gnani import GnaniSTTService, GnaniTTSService
>
> stt = GnaniSTTService(
>     api_key=os.environ["GNANI_API_KEY"],
>     settings=GnaniSTTService.Settings(model="prisma-v3.0", language=Language.HI_IN),
> )
>
> llm = OpenAILLMService(
>     api_key=os.environ["GNANI_API_KEY"],
>     base_url="https://api.vachana.ai/v1",
>     settings=OpenAILLMService.Settings(
>         model="evon-v3.5",
>         max_completion_tokens=150,               # short spoken replies; see Limits
>         extra={"reasoning_effort": "none"},      # thinking off: the first word arrives sooner
>     ),
> )
>
> tts = GnaniTTSService(
>     api_key=os.environ["GNANI_API_KEY"],
>     settings=GnaniTTSService.Settings(model="timbre-v3.0", voice="Avinash", language=Language.HI_IN),
> )
>
> context = LLMContext(
>     messages=[
>         {
>             "role": "system",
>             "content": "You are an AI voice assistant for an online store. "
>             "Reply in one or two short sentences, in the caller's language. "
>             "Do not use lists, markdown or emoji, because your reply is spoken aloud.",
>         }
>     ]
> )
> ```
>
> The rest of the example, including the `Pipeline([...])` order `stt → user aggregator → llm → tts`, stays the same. Remove `GROQ_API_KEY`; Evon uses `GNANI_API_KEY`.

***

## How it works

```text theme={null}
caller audio → Prisma (streaming STT) → text → Evon (streaming, thinking off) → text pieces → Timbre (WebSocket TTS) → audio
```

1. The framework's voice activity detection decides when the caller has finished a turn.
2. Prisma's final transcript is added to the conversation as a `user` message.
3. The framework sends the whole conversation to Evon with `stream: true`.
4. As text arrives, the framework sends it to Timbre a sentence or phrase at a time, so audio starts before the reply is finished.
5. If the caller interrupts, the framework stops the audio and cancels the reply.

***

## Options

| Setting | Recommended | Why |
| - | - | - |
| `reasoning_effort` | `"none"` | Thinking adds time before the first word. See [Thinking](https://docs.gnani.ai/api/LLM/thinking.md). |
| `max_tokens` / `max_completion_tokens` | Small | Spoken replies should be short. The plan maximum is on [Limits](https://docs.gnani.ai/api/LLM/limits.md). |
| System message | Short, "no lists or markdown" | It is sent with every turn, and markdown symbols get read aloud. |
| STT `language` | The caller's language, or a list | A list or `indic-auto` needs `prisma-v3.0`. See [STT models](https://docs.gnani.ai/api/STT/models/overview.md). |
| TTS `voice` and `language` | A `timbre-v3.0` voice | `timbre-v3.0` voices speak all ten languages. See [TTS](https://docs.gnani.ai/api/TTS/tts-inference.md). |

***

## Gotchas

> [!WARNING]
>
> **One request at a time on Free and Pay-as-you-go plans.** A voice agent that starts a new reply while the last one is still streaming, for example after an interruption, can get `429 RATE_LIMITED`. Make sure the old reply is cancelled first, and see [Limits](https://docs.gnani.ai/api/LLM/limits.md) for your plan.

* **Thinking can empty the reply.** If thinking is left on, it can use the whole `max_tokens` budget and the reply comes back empty with `finish_reason: "length"`.
* **Every turn resends the conversation.** Long calls use your [daily token quota](https://docs.gnani.ai/api/LLM/limits.md) faster. Trim old turns in long calls.
* **Personal data in replies is masked.** If the model would say a phone number, the text contains `[REDACTED_PHONE]`, and the TTS would read that out. Have your own code speak such details. See [Safety and privacy](https://docs.gnani.ai/api/LLM/safety.md).
* **Say it is an AI.** Tell callers at the start that they are talking to an AI assistant, as the greeting above does.

> [accordion] Using another framework
>
> Any framework that can call an OpenAI-compatible Chat Completions API can use Evon. Set the base URL to `https://api.vachana.ai/v1`, the model to `evon-v3.5` and the API key to your Gnani key, and send `reasoning_effort: "none"` for voice.

***

## Related

> [card] [LiveKit plugin](https://docs.gnani.ai/livekit/introduction.md)
>
> Prisma and Timbre settings for LiveKit Agents.

> [card] [Pipecat plugin](https://docs.gnani.ai/pipecat/introduction.md)
>
> Prisma and Timbre services for Pipecat pipelines.

> [card] [Streaming](https://docs.gnani.ai/api/LLM/streaming.md)
>
> How streamed replies arrive, chunk by chunk.

> [card] [Thinking](https://docs.gnani.ai/api/LLM/thinking.md)
>
> When to turn thinking off, and what it costs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.