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

# Voice Agents

> The reusable primitive that defines your avatar's persona

A **voice agent** is a stored, reusable definition of your avatar's persona — how it sounds and how it thinks. It bundles that persona into a single resource you reference by `id` when starting a session — instead of wiring up voice, context, and language on every request.

Define your avatar's persona once, then reuse it across sessions and embeds. The same agent can be reused with different per-session values each time.

Build and manage your voice agents in the dashboard at [app.liveavatar.com/voice-agent](https://app.liveavatar.com/voice-agent). Each agent has an `id` you reference when starting a session.

## Agent types

A voice agent has a stored `agent_type` that determines how the session is built and which configuration applies. The server resolves the type from the agent `id` — you do not pass it at session time.

### `liveavatar_agent`

Backed by LiveAvatar's managed conversational pipeline (STT → LLM → TTS). This is a **FULL Mode** agent: LiveAvatar runs the entire real-time stack. A `liveavatar_agent` builds its persona from the two building blocks documented in this section:

* A **[voice](/docs/core-concepts/voices)** — how the avatar sounds.
* A **[context](/docs/core-concepts/contexts)** — what the avatar knows and how it behaves.

See [FULL Mode Overview](/docs/full-mode/overview) for the pipeline details.

### `elevenlabs_agent`

Backed by an ElevenLabs-hosted agent, which handles the conversational AI while LiveAvatar renders the avatar video. An `elevenlabs_agent` produces a **LITE Mode** session even when referenced from a FULL Mode token request.

See the [ElevenLabs Agent Connector](/docs/lite-mode/connectors/elevenlabs-agent) for setup.

## Referencing a voice agent

Pass the stored agent `id` where the request accepts one:

* **Session tokens** — supply a `voice_agent` object on a FULL Mode `POST /v1/sessions/token` request. Mutually exclusive with `avatar_persona`.
* **Embeds** — supply `voice_agent_id` on `POST /v2/embeddings`. Mutually exclusive with `voice_id` / `context_id`.

```json theme={null}
{
  "mode": "FULL",
  "avatar_id": "<avatar_id>",
  "voice_agent": {
    "id": "<voice_agent_id>"
  }
}
```

The server resolves the agent's type and builds the session accordingly.

## Per-session overrides

A voice agent stores defaults, but you can layer per-session values over them at creation time. Overrides apply to that session only — they do not modify the stored agent. Which overrides are accepted depends on the resolved `agent_type`; an override that does not apply is **rejected with a `400`** rather than silently ignored.

| Override            | `liveavatar_agent`                                   | `elevenlabs_agent` |
| ------------------- | ---------------------------------------------------- | ------------------ |
| `language`          | Layered over the agent's stored language             | Rejected (`400`)   |
| `dynamic_variables` | Substituted into the context's `${var}` placeholders | Rejected (`400`)   |

```json theme={null}
{
  "mode": "FULL",
  "avatar_id": "<avatar_id>",
  "voice_agent": {
    "id": "<voice_agent_id>",
    "language": "en",
    "dynamic_variables": {
      "user_name": "Jordan",
      "plan": "Pro"
    }
  }
}
```

<Note>
  `dynamic_variables` here is mutually exclusive with the top-level `dynamic_variables` (`400` if both are set). Values must be strings. At most 50 entries, with keys ≤ 64 chars and values ≤ 1000 chars.
</Note>