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. 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 — how the avatar sounds.
- A context — what the avatar knows and how it behaves.
See 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 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.
{
"mode": "FULL",
"avatar_id": "<avatar_id>",
"voice_agent": {
"id": "<voice_agent_id>"
}
}
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) |
{
"mode": "FULL",
"avatar_id": "<avatar_id>",
"voice_agent": {
"id": "<voice_agent_id>",
"language": "en",
"dynamic_variables": {
"user_name": "Jordan",
"plan": "Pro"
}
}
}
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.
