> ## Documentation Index
> Fetch the complete documentation index at: https://unmute.ai/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Unmute compiles to exactly three targets. Pipecat and LiveKit are code targets: compile writes a Python project you run. SLNG is a hosted target: compile writes a deployment body and SLNG runs the agent, so it has no `unmute dev`. Those three are the only values `provider` accepts in `targets.yaml`. Deepgram and ElevenLabs appear in these docs as model vendors, which is not the same thing as a target, and `slng` is both.
> The Go structs in `internal/spec` and `internal/ir` are the schema truth. Check a field against them, or run `unmute validate`, rather than against what you remember.
# Live model
> Configure the OpenAI live model, its voice, and the backend that runs tools.
Connect a live voice model to the reasoning backend that runs your agent's tools.
The agent binds a named `models.live` entry through `live:`; that entry can bind an OpenAI `models.think` entry through `backend:`.
On this page:
* [Quickstart](#quickstart) - start with a working package
* [Configure the entry](#1-configure-the-live-entry) - fields and defaults
* [Attach the backend](#2-attach-a-backend-for-tools) - tools and knowledge
* [Pipecat](#pipecat) - target support
* [LiveKit Agents](#livekit-agents) - target support
* [Advanced](#advanced) - session behavior and limits
* [Troubleshooting](#troubleshooting) - symptoms and fixes
* [Where to go next](#where-to-go-next) - guides and references
## Quickstart
From a clone of the [examples](https://github.com/slng-ai/unmute/tree/main/examples), set `OPENAI_API_KEY` in your shell or `examples/takeaway-orders/.env`.
The package is complete and includes a live model, backend, local tools, and knowledge lookup.
```sh Terminal, from the repository root theme={null}
unmute validate examples/takeaway-orders
unmute compile examples/takeaway-orders
unmute dev examples/takeaway-orders --target pipecat
```
Ask for salt and pepper chicken and egg fried rice for collection.
Check that the tool results determine the order and its total.
For a new package, follow the complete [Live quickstart](/build/architecture/live#quickstart).
## 1. Configure the live entry
To reuse the takeaway setup, replace its model palette and live binding with this **replacement fragment**.
It uses shorter names, `voice` and `fast`. Keep the existing instructions, tool attachments, and other package settings.
```yaml examples/takeaway-orders/agent.yaml theme={null}
architecture: live
models:
live:
- name: voice
provider: openai
model: gpt-live-1
voice: marin
backend: fast
think:
fast:
provider: openai
model: gpt-5.6-terra
agents:
counter:
instructions: instructions.md
live: voice
```
Set `architecture: live` explicitly. If omitted, the architecture is `cascade`.
The agent's `live:` binding replaces its `think:` and `speak:` bindings.
`name`, `provider`, and `model` are required. `voice`, `backend`, and `description` are optional unless the tool setup requires a backend.
Name used by the agent's `live:` binding. It must be unique across model sections.
OpenAI is the supported live provider on both code targets. There is no wildcard provider route.
Provider model ID, such as `gpt-live-1`. It is forwarded as written; access and availability are checked by the provider when the session starts.
Provider voice ID. Omitted means the provider's default voice.
OpenAI backend for tools and reasoning. Required when the agent has tools, including knowledge lookup. The referenced entry cannot set `endpoint_env`.
Optional note for package readers. It has no runtime effect.
A live entry does not accept `temperature`, `language`, `speed`, `params`, `pace`, `endpoint_env`, or per-target model overrides.
Validation refuses these settings rather than ignoring them.
## 2. Attach a backend for tools
With the replacement names above, `voice` hands tool work to `fast`.
The backend calls the attached local and knowledge tools, and the live model speaks the result.
The backend must be at OpenAI. Both models and the knowledge embeddings use `OPENAI_API_KEY`.
Only the backend's **model name** reaches the live service.
Its `params:` do not configure the live session, even when they appear in `compile-report.json`.
With no attached tools, `backend:` is optional; requests that need a backend may be declined.
Use the [Live tool walkthrough](/build/architecture/live#2-give-the-backend-a-tool) to attach a new tool.
Use [Knowledge bases](/build/tools/knowledge) for document lookup.
## Pipecat
| Provider | Configuration |
| -------- | ------------------------------------------------------------------------------ |
| `openai` | `gpt-live-1`, `OPENAI_API_KEY`, and an OpenAI backend when tools are attached. |
Pipecat keeps local voice activity detection for inactivity and reply measurements.
It does not use that detector to end the live model's turn.
## LiveKit Agents
| Provider | Configuration |
| -------- | ------------------------------------------------------------------------------ |
| `openai` | `gpt-live-1`, `OPENAI_API_KEY`, and an OpenAI backend when tools are attached. |
LiveKit uses the model's speech events and adds no local voice activity detector to the live session.
Both targets support browser audio. The slng target refuses `architecture: live`.
## Advanced
The session fixes its instructions, model, and voice when it starts.
A greeting is an opening instruction, so the model can paraphrase it.
The model also controls interruptions; `conversation.interruption` is refused.
Inactivity nudges ask the model to check whether the caller is still there.
The inactivity end timer ends the call.
The dev page shows speech transcripts, replies, and backend tool calls with their durations.
It does not show per-reply first-token or request timing for live speech.
Live serves one agent, with local and webhook tools, built-in tools, and knowledge lookup.
| Unsupported setting | Reason |
| -------------------------------- | ---------------------------------------------------------------------- |
| Tasks and transfers | The session has no `tasks`, task groups, `handoffs`, or `escalations`. |
| Listen, speak, and turn sections | The model listens, speaks and decides the turn itself. |
| Variables and pre-fetch | This shape carries no call state yet. |
| Tracing | This shape has no traced worker yet. |
| MCP tools | This shape cannot start and close a server connection yet. |
| Phone connections | Live compiles for the browser route in this version. |
Use [Cascade](/build/architecture/cascade) when your workflow needs these features.
See the [architecture comparison](/build/architecture/overview#2-check-what-your-package-needs) before switching an existing package.
## Troubleshooting
### Validation asks for a backend
The agent has a tool, but its live entry has no backend.
**Fix:** set `backend: fast` and provide the OpenAI think entry shown above.
### A backend setting has no effect
The live service receives only the backend model name.
**Fix:** remove unsupported tuning assumptions; choose a suitable backend model and verify the result in a call.
### The first call fails with a provider error
The API key may lack access to the selected model or voice.
**Fix:** read the provider error in the dev logs and check both the live and backend model IDs.
### Validation refuses a task or phone connection
Those features need the cascade architecture.
**Fix:** follow the [switching guide](/build/architecture/overview), or keep this package as a single browser agent.
## Where to go next
Start from a complete package and add a tool.
Compare live, realtime, and cascade.