Cartesia Agent Connector

The Cartesia Agent Connector bridges Cartesia Agents with LiveAvatar. Cartesia handles the conversational AI while LiveAvatar renders the avatar video. A Cartesia Agent owns its voice, prompt, and language on Cartesia’s side — configure those on your Cartesia agent.

Requirements

Cartesia API key
Cartesia Agent ID — create and configure your agent at play.cartesia.ai/agents

Setup

1. Register your Cartesia API key:

curl -X POST https://api.liveavatar.com/v1/secrets \
  -H "X-API-KEY: <YOUR_API_KEY>" \
  -H "content-type: application/json" \
  -d '{
    "secret_type": "CARTESIA_API_KEY",
    "secret_value": "<cartesia_api_key>",
    "secret_name": "Cartesia Agent Key"
  }'

The response returns a secret_id. LiveAvatar stores the key by reference — it is never sent inline on a session request. See Secrets. 2. Start a session with the connector: There are two ways to point a session at your Cartesia agent.

Stored voice agent (recommended)
Inline config

Save the configuration once as a voice agent of type cartesia_agent, then reference it by id on every session:

{
  "mode": "FULL",
  "avatar_id": "<avatar_id>",
  "voice_agent": {
    "id": "<voice_agent_id>"
  }
}

The server resolves the stored agent_type and builds a LITE Mode session — even from a FULL Mode token request. Create and manage voice agents in the dashboard at app.liveavatar.com/voice-agent.Per-session language and dynamic_variables overrides do not apply to a Cartesia agent and are rejected rather than silently ignored:

400: voice_agent.language, voice_agent.dynamic_variables do(es) not apply to a
voice_agent of type 'cartesia_agent'.

Pass the agent details directly on the session token request:

{
  "mode": "LITE",
  "avatar_id": "<avatar_id>",
  "cartesia_agent_config": {
    "secret_id": "<secret_id>",
    "agent_id": "<cartesia_agent_id>"
  }
}

Both fields are required when cartesia_agent_config is present. cartesia_agent_config is mutually exclusive with elevenlabs_agent_config.

A stored voice agent is the recommended path: the configuration lives in one place, is reusable across sessions and embeds, and can be changed without redeploying your app.

How it works

A LiveKit room is automatically created (no WebSocket endpoint returned)
LiveAvatar dispatches a worker that handles interaction with your Cartesia Agent
Agent audio drives avatar animation in real time

The Cartesia Agent Connector uses the FULL Mode event system, not standard LITE Mode events. The WebSocket command events described in the LITE Mode Events page do not apply here. See the Events section below for details.

Events

Events are exchanged over the LiveKit data channel and differentiated by LiveKit room topic:

agent-control — commands you send to the avatar
agent-response — events the server sends to you

The following FULL Mode response events fire on every Cartesia session, on the agent-response topic:

Event	Source
`user.speak_started` / `user.speak_ended`	LiveKit user-state changes
`user.transcription_chunk` / `user.transcription`	Streaming and final user transcription
`avatar.transcription_chunk` / `avatar.transcription`	Streaming and final agent text
`avatar.speak_started` / `avatar.speak_ended`	Avatar TTS lifecycle
`session_stopped`	Session lifecycle (includes `stop_reason`)

When the Cartesia Agent cleanly closes its connection (e.g. the agent hangs up), the session ends with a session_stopped event carrying stop_reason: AGENT_HANG_UP.

Billing

LiveAvatar: 1 credit per session minute (avatar video only)
Cartesia: charges separately for agent usage

Getting Started

Core Concepts

FULL Mode

LITE Mode

Socials

FAQ

Requirements

Setup

How it works

Events

Billing

​Requirements

​Setup

​How it works

​Events

​Billing

Requirements

Setup

How it works

Events

Billing