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

# Prism LiveKit plugin reference

> Configure Prism settings, tool calls, startup retries, playback, and conversation history in the LiveKit Rime plugin.

`rime.realtime.RealtimeModel` connects a LiveKit agent directly to Prism with your Rime API key. For installation and a complete agent, use the [LiveKit quickstart](https://docs.rime.ai/docs/prism/livekit.md). These settings apply to the Rime plugin.

## Session behavior

Prism handles speech input, turn detection, and speech output. Pass the model as `AgentSession(llm=model)` without separate `stt`, `tts`, `vad`, or `turn_detection` settings.

| Feature | Behavior |
| - | - |
| Connection | The default endpoint is `wss://prism.api.rime.ai/v1/realtime`. The plugin sends the server's `RIME_API_KEY`. |
| Language and voices | English, with `aurora`, `wawona`, `brando`, or `astra` |
| Caller transcripts | The plugin passes on interim and final transcripts when Prism sends them. A final transcript can arrive after Prism starts its reply. |
| Typed input | The plugin accepts typed input through conversation history. Set `text_input=False` in `room_io.RoomOptions` for a voice-only room. |
| Speech | Use `generate_reply()` to ask Prism to speak. `session.say()` needs a separate text-to-speech model. |
| Memory | Each session starts fresh. You can supply earlier text and completed tool calls, but a dropped connection cannot resume. |
| Unsupported features | Video input, manual audio commit, per-reply tools, and turning off server turn detection |

Close the model with `await model.aclose()` when the job ends. The quickstart registers this call with `ctx.add_shutdown_callback`.

## Change settings and switch agents

Use `await agent.update_instructions(...)` and `await agent.update_tools(...)` to update agent settings. These methods wait for Prism to acknowledge the change.

Use `model.update_options(voice="...")` without `await` to queue a voice change. It returns before Prism accepts the change. The plugin applies queued updates in order and reports refusals through `error` events. A recoverable refusal leaves the session open with its last accepted settings.

Handoffs update instructions, history, and tools separately. They are not atomic. Use the [shared history mode](#recover-a-refused-history-update) to preserve pending tool calls when switching agents or running tasks inside tools.

## Control tool calls

Prism chooses when to call your `@function_tool` functions. LiveKit runs the functions and returns their results to Prism. Forced or named tool choices are not supported.

`tool_choice="none"` temporarily removes tools from the session. It is not an atomic per-reply setting and can also affect replies that start from caller speech during the change.

Prism can speak a filler phrase while a tool runs. It can skip the phrase if it already spoke before the call.

## Configure startup retries

The plugin retries initial HTTP refusals with status 408, 429, 500, 502, 503, or 504. Other HTTP errors, unknown connection failures, and initialization timeouts fail without retry. An established conversation is not automatically reconnected.

These options allow up to three retries after the first attempt, with a 10-second limit for each connection attempt and a 30-second budget for all attempts and delays:

```python theme={null}
from livekit.agents import APIConnectOptions
from livekit.plugins import rime

model = rime.realtime.RealtimeModel(
    voice="aurora",
    conn_options=APIConnectOptions(max_retry=3, retry_interval=2, timeout=10),
    startup_timeout=30,
)
```

The default retry delays are 0.1, 2, and 2 seconds. A valid server `Retry-After` value sets the minimum delay. If that delay cannot fit in the startup budget, startup ends with the original refusal. Closing the session cancels startup and pending delays, but waits for SDK cleanup. Set `max_retry=0` to disable retries.

## Choose playback behavior

The default `playback="auto"` uses Prism's estimate of when normal playback ends. When the caller interrupts, LiveKit reports the played position so Prism can truncate the reply.

For tests that need text and tools without output audio, create the model with discard mode:

```python theme={null}
model = rime.realtime.RealtimeModel(voice="aurora", playback="discard")
```

Discard mode keeps text and tools active without playing audio. Prism still generates and sends audio to the plugin.

## Recover a refused history update

The default `context_mode="shared"` preserves omitted messages and pending tool calls when LiveKit switches agents or runs a task inside a tool. An empty context update does not clear Prism's history.

To replace or clear history, create the model with `context_mode="strict"` and use `await agent.update_chat_ctx(target_context)`. Edits that rebuild history require no active reply or pending tool call. Pause other context edits and handoffs during the update. Each write has its own acknowledgment, so replacement is not atomic.

A refused or partly applied update raises `PrismHistoryUpdateError`, imported from `livekit.plugins.rime.realtime`. Inspect `status`, `recoverable`, and `confirmed_chat_ctx` to see what Prism accepted. Local history can differ from Prism's history after a failure. Known rejections and partial updates leave the session usable for later independent operations. The plugin preserves acknowledged writes and does not submit accepted tool results again or execute their tools again.

Rejected typed input does not start a reply. If an update only appends tool results and Prism accepts a result that needs a reply, LiveKit can continue from that result even if another result fails. Other failed updates stop their dependent replies. Unknown write outcomes, such as a missing acknowledgment, require a new session.


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