Skip to main content
A persona-agnostic voice agent built on LiveKit Agents. Each conversation persona maps to its own Moss index, and the active persona is set via room metadata at call time — no restarts or code changes needed when you add a new knowledge domain.
Full example — see the Generalist Voice Agent cookbook for the complete runnable demo with sample docs and persona config.

Why Moss for voice agents?

Voice agents are latency-sensitive. A retrieval step that takes 200–500ms is audible as a pause. Moss loads indexes into local memory at session start so every moss_search call during the call returns in ~1–10ms — fast enough to stay below the perceptual threshold. The persona model also means you can run a single agent binary against many knowledge bases. Add hr_policies as a new index, register it in personas.json, and the next call routed to that persona immediately has access to it.

Architecture

Required tools

Integration guide

1

Installation

2

Environment setup

.env
3

Index your documents

Place .txt or .md files in a folder named after the knowledge domain. The folder name becomes the Moss index name and is what the agent routes to.
Run create_index.py once per folder:
To add a new knowledge base later, index a new folder — no agent restart needed.
4

Register personas

personas.json maps a persona ID to an index name and a system prompt. Each persona is a distinct voice and knowledge domain.
personas.json
5

Build the voice agent

MossVoiceAgent extends livekit.agents.Agent. The @function_tool decorator exposes moss_search to the LLM. Each worker process creates one MossClient with a cache_path in prewarm, and each call starts loading its persona’s index before ctx.connect(), so the load runs while the call connects and retrieval stays in local memory. See Process model and index loading.
6

Start the agent and connect

Open the LiveKit Agents Playground, enter your LiveKit credentials, and connect. To test a different persona, set the room metadata before connecting:

Switching personas at call time

The persona is resolved from room metadata at the start of each session. This means you can route different callers to different knowledge bases — support line vs. product FAQ vs. HR helpdesk — from a single running agent worker. Each call loads only its persona’s index, from the disk cache when the cloud copy is unchanged. Adding a new persona is three steps: add files to a docs folder, run create_index.py, and add a new entry to personas.json. No restart required.