> ## 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

> Run an OpenAI live voice agent and give it a reasoning backend for tools and knowledge.

Let a live voice model hold the conversation while a reasoning backend handles its tools.
`models.live` names the voice model; `backend:` points to an OpenAI entry in `models.think`.
The live model decides when to speak and how to respond to interruptions.

On this page:

* [Quickstart](#quickstart) - a complete live agent
* [Pros and cons](#pros-and-cons) - strengths and limits
* [Bind the voice](#1-bind-the-live-model) - select the model
* [Attach tools](#2-give-the-backend-a-tool) - let it do useful work
* [Try the conversation](#3-try-tools-and-knowledge-in-a-call) - verify the result
* [Advanced](#advanced) - defaults and limits
* [Troubleshooting](#troubleshooting) - fix setup and call failures
* [Where to go next](#where-to-go-next) - references and alternatives

## Quickstart

Create a new package with a LiveKit target. If initialization opens the console, select LiveKit and finish creating the package.

```sh Terminal theme={null}
unmute init voice-desk
```

Replace `voice-desk/agent.yaml` with this **complete file**:

```yaml voice-desk/agent.yaml theme={null}
version: 1
name: voice-desk
architecture: live
entry_agent: desk
secrets:
  - OPENAI_API_KEY
models:
  live:
    - name: voice
      provider: openai
      model: gpt-live-1
      voice: marin
      backend: reasoning
  think:
    reasoning:
      provider: openai
      model: gpt-5.6-terra
agents:
  desk:
    instructions: instructions.md
    live: voice
channels:
  web:
    kind: realtime_audio
capacity:
  peak_sessions: 1
  max_sessions: 2
  avg_session_duration: 3m
```

Keep the scaffold's `targets.yaml`, but remove its target-level `models:` overrides because the model palette above replaces the scaffold's.
Keep its framework provider and version pin, and remove any phone `connection:` for this browser example. Replace `voice-desk/instructions.md` with this complete prompt:

```markdown voice-desk/instructions.md theme={null}
You are a friendly information desk. Answer in short spoken sentences.
Ask one question at a time. If you do not know an answer, say so.
```

Set `OPENAI_API_KEY` in your shell or the package's `.env`, then run:

```sh Terminal theme={null}
unmute validate voice-desk
unmute compile voice-desk
unmute dev voice-desk --target livekit
```

Use Docker for this LiveKit run. The [Pipecat target](/targets/pipecat) is another option; it runs locally with `uv`.
The example below stays with this same `desk` agent.

## Pros and cons

Pick Live when you want the model to manage the spoken exchange and send
tool work to a backend. It fits an agent that can work within the model's
own turn and voice behavior.

| Pros                                                               | Cons                                                                                        |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| The model hears audio directly and manages turns and interruptions | Unmute exposes no separate turn detector or interruption settings here                      |
| The model can keep speaking while backend work runs                | Tool completion still waits for that backend and the tools it calls                         |
| A dedicated backend handles tool requests and reasoning            | The backend must use the same provider; it is not an unrestricted second pipeline           |
| Tools and knowledge searches remain available                      | Unmute currently supports no tasks, handoffs, saved variables, tracing, or phone route here |

Live can respond with fewer speech-processing stages, but is not guaranteed
to beat Realtime or a tuned Cascade on every interaction. Compare both reply
time and successful tool completion.

Choose [Realtime](/build/architecture/realtime) for selectable turn modes or a
separate voice. Choose [Cascade](/build/architecture/cascade) when the workflow
needs more steps and state. The [overview](/build/architecture/overview#pros-and-cons)
compares all three and links the LiveKit and Coval articles.

## 1. Bind the live model

The quickstart's `desk` names `voice` through its `live:` binding.
That entry uses `gpt-live-1` and names `reasoning` as its backend.
Both use `OPENAI_API_KEY`; your account must have access to both models.

<ParamField path="architecture" type="cascade | realtime | live" required>
  Set `live` explicitly. Omitted means `cascade`, which cannot use a live binding.
</ParamField>

<ParamField path="live" type="a models.live entry name" required>
  Agent-level binding. It replaces `think:` and `speak:` on this agent.
</ParamField>

<ParamField path="backend" type="a models.think entry name">
  OpenAI reasoning entry used by the live model. Required when the agent has tools, including knowledge lookup. It cannot use `endpoint_env`.
</ParamField>

See [Live model fields](/models/live) for the full entry reference.
Do not add separate listen, speak, or turn sections; live owns those jobs.

## 2. Give the backend a tool

Add one local tool to the same desk. Create these two **complete new files**:

```yaml voice-desk/tools/opening_hours.yaml theme={null}
description: Look up the information desk's opening hours.
input:
  type: object
  properties: {}
local:
  handler: tools/opening_hours.py
```

```python voice-desk/tools/opening_hours.py theme={null}
def opening_hours():
    return {"hours": "Monday to Friday, nine in the morning to five in the afternoon."}
```

Merge these attachments into `agent.yaml`. Keep the existing `instructions` and `live` binding under `desk`:

```yaml voice-desk/agent.yaml theme={null}
tools:
  - opening_hours
agents:
  desk:
    tools:
      - opening_hours
```

Append this instruction to the existing prompt:

```markdown voice-desk/instructions.md theme={null}
Use opening_hours when asked when the desk is open. Read the returned hours.
```

The live model sends the request to its backend. The backend requests a tool call, the generated application runs the handler, and the live model speaks the result.
A tool's returned data should determine the answer; the model should not invent it.

## 3. Try tools and knowledge in a call

Stop the earlier dev run, then validate and restart:

```sh Terminal theme={null}
unmute validate voice-desk
unmute dev voice-desk --target livekit
```

Ask when the desk opens, then interrupt with a follow-up question.
Check that the dev page records the tool and that the spoken answer matches its result.

For document lookup, follow [Knowledge bases](/build/tools/knowledge) and attach the resulting search tool to this same agent.
It runs through the backend too. The complete [takeaway example](https://github.com/slng-ai/unmute/tree/main/examples/takeaway-orders) combines orders and knowledge on both frameworks.

## Advanced

<Accordion title="Defaults and supported settings">
  The live entry's voice is optional; omitted means the provider's default.
  With no tools, the backend is optional, but requests needing one may be declined.
  The backend binding forwards its model name; do not rely on its `params:` being applied to the live session.
  A greeting is an opening instruction, so its exact wording can change.
  See [Live model](/models/live) for fields and target differences.
</Accordion>

<Accordion title="Switch an existing package">
  Use the [switching steps](/build/architecture/overview#3-replace-the-models-and-agent-bindings).
  The current Live integration fixes instructions and tool setup at session start.
  It supports one agent and browser audio on Pipecat and LiveKit.
  These are limits of Unmute’s integration, not of every speech-to-speech API.
  It does not support tasks, handoffs, variables, pre-fetch, tracing, MCP tools, or phone connections.
  Remove `conversation.interruption`; the model manages interruptions itself.
  Keep cascade when these features are part of your required workflow.
</Accordion>

## Troubleshooting

### Validation says the live model needs a backend

An attached tool has no reasoning backend to run it.
**Fix:** add `backend: reasoning` to the live entry and keep the OpenAI `models.think.reasoning` entry from the quickstart.

### The model speaks but cannot use my tool

The tool may be unattached, its arguments may be wrong, or its handler may return a refusal.
**Fix:** check the dev tool row and logs, verify both tool attachments, and compare the result with what the agent said.
See [Local tools](/build/tools/python) for the tool contract.

### The call fails at session start

A configured model or voice may be unavailable to the API key.
**Fix:** read the provider error in the dev logs and verify access to the live model and its backend.

### The greeting sounds different

The live model paraphrases the opening instruction.
**Fix:** write the intended meaning in the greeting; use cascade if exact synthesized wording is required.

## Where to go next

<Columns cols={2}>
  <Card title="Live model fields" icon="microphone" href="/models/live">Review fields and target support.</Card>
  <Card title="Realtime" icon="audio-lines" href="/build/architecture/realtime">Choose turn detection or another voice.</Card>
</Columns>