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

# Cartesia Agent Connector

> Bridge Cartesia Agents with LiveAvatar for real-time avatar video

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](https://play.cartesia.ai/agents)

## Setup

**1. Register your Cartesia API key:**

```bash theme={null}
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](/docs/core-concepts/secrets).

**2. Start a session with the connector:**

There are two ways to point a session at your Cartesia agent.

<Tabs>
  <Tab title="Stored voice agent (recommended)">
    Save the configuration once as a [voice agent](/docs/core-concepts/voice-agents) of type `cartesia_agent`, then reference it by `id` on every session:

    ```json theme={null}
    {
      "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](https://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'.
    ```
  </Tab>

  <Tab title="Inline config">
    Pass the agent details directly on the session token request:

    ```json theme={null}
    {
      "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`.
  </Tab>
</Tabs>

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

```mermaid theme={null}
sequenceDiagram
    participant User
    participant LiveAvatar
    participant Cartesia Agent

    User->>LiveAvatar: Start LITE session with agent config
    LiveAvatar->>Cartesia Agent: Connect worker to agent
    User->>Cartesia Agent: Audio input (speech)
    Cartesia Agent->>Cartesia Agent: Audio orchestration + LLM
    Cartesia Agent->>LiveAvatar: Audio output
    LiveAvatar->>User: Avatar video stream with lip sync
```

<Warning>
  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](/docs/lite-mode/events) page do not apply here. See the [Events](#events) section below for details.
</Warning>

## 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](/docs/full-mode/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