Skip to main content
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.

​
cartesia_agent

Backed by a Cartesia-hosted agent, which handles the conversational AI while LiveAvatar renders the avatar video. Like an elevenlabs_agent, it produces a LITE Mode session even when referenced from a FULL Mode token request. A Cartesia agent owns its voice and prompt on Cartesia’s side, so its stored configuration is just two fields: the agent_id of your Cartesia agent, and the secret_id of a stored CARTESIA_API_KEY secret. See the Cartesia 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.
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. A provider-hosted agent (elevenlabs_agent, cartesia_agent) is used as-is — configure its language and prompt variables on the provider side.
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.