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

# Agora

> Agora Conversational AI Engine — LiveAvatar provider integration

Agora's [Conversational AI Engine](https://docs.agora.io/en/conversational-ai/overview/product-overview) ships LiveAvatar as a first-class avatar provider. You keep Agora's voice orchestration (ASR, LLM, TTS) and Agora SD-RTN transport — LiveAvatar adds the avatar video participant inside the same channel.

<Note>
  This page assumes you already have an Agora project with Conversational AI enabled and can start a voice agent against an Agora RTC channel. If not, start with Agora's [Conversational AI quickstart](https://docs.agora.io/en/conversational-ai/get-started/quickstart), or pick a different [integration path](/docs/lite-mode/integration-paths).
</Note>

<Tip>
  Upstream reference: [Agora docs — LiveAvatar by HeyGen](https://docs.agora.io/en/conversational-ai/models/avatar/heygen).
</Tip>

## Prerequisites

* A LiveAvatar account and **API key**. Sign up at [app.liveavatar.com](https://app.liveavatar.com).
* An **Agora project** with Conversational AI Engine enabled, plus an App ID and Basic Auth credentials for the REST API.
* A way to mint Agora **RTC tokens** for at least three participants: the end user, the Agora agent, and the LiveAvatar avatar. The agent and avatar tokens need publish permission; the user token needs both publish (microphone) and subscribe.

## Installation

There is no SDK to install on your side. The integration is server-driven: you call Agora's `join` REST endpoint with an `avatar` block, and Agora's backend brings LiveAvatar into your channel.

## Configuration

LiveAvatar is selected by adding an `avatar` block under `properties` in the Agora `join` request body:

```json theme={null}
{
  "avatar": {
    "vendor": "liveavatar",
    "enable": true,
    "params": {
      "api_key": "<liveavatar_api_key>",
      "avatar_id": "<liveavatar_avatar_id>",
      "quality": "high",
      "agora_uid": "<avatar_rtc_uid>",
      "agora_token": "<avatar_rtc_token>"
    }
  }
}
```

| Parameter               | Required | Notes                                                                                                     |
| ----------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `api_key`               | yes      | Your LiveAvatar key from [app.liveavatar.com](https://app.liveavatar.com).                                |
| `avatar_id`             | yes      | The avatar to render.                                                                                     |
| `quality`               | yes      | `high` (720p), `medium` (480p), or `low` (360p).                                                          |
| `agora_uid`             | yes      | RTC UID the avatar publishes under. Must be distinct from your `agent_rtc_uid` and any `remote_rtc_uids`. |
| `agora_token`           | yes      | RTC token minted for `agora_uid` on the same channel as the agent, with publish permission.               |
| `activity_idle_timeout` | no       | Seconds of silence before the avatar tears down. Default `120`.                                           |
| `disable_idle_timeout`  | no       | Default `false`. Set `true` to keep the avatar alive indefinitely; overrides `activity_idle_timeout`.     |

<Warning>
  **TTS must be 24 kHz.** LiveAvatar consumes audio at a 24,000 Hz sample rate. Any other rate in the `tts` block will error at session start.
</Warning>

## How Agora + LiveAvatar fit together

An Agora **RTC channel** hosts the conversation between three participants:

| Participant                       | Publishes                                    | Subscribes to                |
| --------------------------------- | -------------------------------------------- | ---------------------------- |
| **End user**                      | Microphone audio                             | Avatar audio + video         |
| **Agora agent** (`agent_rtc_uid`) | (no media; forwards TTS audio to LiveAvatar) | User microphone              |
| **LiveAvatar** (`agora_uid`)      | Lip-synced audio + video                     | TTS audio forwarded by Agora |

The avatar is its own RTC publisher. Agora's Conversational AI Engine routes synthesized TTS audio to LiveAvatar, which lip-syncs and publishes audio + video back into the channel under `agora_uid`. Your frontend subscribes to that UID for the avatar's tracks.

```mermaid theme={null}
graph TB
    subgraph Channel["Agora RTC channel (you own)"]
        Agent["Agora agent<br/>(ASR / LLM / TTS)"]
        User["End user"]
        Avatar["LiveAvatar<br/>avatar participant"]
    end
    User -->|"mic audio"| Agent
    Agent -->|"24 kHz TTS audio"| Avatar
    Avatar -->|"lip-synced audio + video"| User
```

### How the session starts up

1. **You mint tokens.** Issue Agora RTC tokens for the agent UID and the avatar UID against the channel your end user will join.
2. **You POST `/join`.** Call `https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/join` with `properties.avatar` set to the LiveAvatar block above, alongside your `llm`, `asr`, and `tts` configuration. The response returns an `agent_id` — store it; you will need it to stop the session.
3. **Agora starts the agent.** The Conversational AI Engine joins the channel as `agent_rtc_uid` and starts its ASR → LLM → TTS loop.
4. **Agora spawns LiveAvatar.** Using your `api_key`, `avatar_id`, `agora_uid`, and `agora_token`, Agora's backend opens a LiveAvatar session and the avatar joins the channel as a publisher.
5. **Your frontend subscribes.** The end user joins the channel, subscribes to the avatar's audio + video tracks, and the conversation runs.

### Stopping the session

POST to `https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents/:agent_id/leave` with the same `Authorization: Basic` header used for `/join`, where `:agent_id` is the value returned from `/join`. Agora tears down the agent and the LiveAvatar session together.

## Minimal example

ElevenLabs TTS at 24 kHz, pointed at LiveAvatar:

```bash theme={null}
curl --request POST \
  --url "https://api.agora.io/api/conversational-ai-agent/v2/projects/$AGORA_APP_ID/join" \
  --header "Authorization: Basic $AGORA_BASIC_AUTH" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "liveavatar-session-1",
    "properties": {
      "channel": "demo-room",
      "token": "<agent_rtc_token>",
      "agent_rtc_uid": "1000",
      "remote_rtc_uids": ["2000"],
      "idle_timeout": 120,
      "asr": { "language": "en-US" },
      "llm": {
        "url": "https://api.openai.com/v1/chat/completions",
        "api_key": "<openai_key>",
        "system_messages": [
          { "role": "system", "content": "You are a helpful avatar." }
        ]
      },
      "tts": {
        "vendor": "elevenlabs",
        "params": {
          "base_url": "wss://api.elevenlabs.io/v1",
          "key": "<elevenlabs_key>",
          "model_id": "eleven_flash_v2_5",
          "voice_id": "pNInz6obpgDQGcFmaJgB",
          "sample_rate": 24000
        }
      },
      "avatar": {
        "vendor": "liveavatar",
        "enable": true,
        "params": {
          "api_key": "<liveavatar_api_key>",
          "avatar_id": "<liveavatar_avatar_id>",
          "quality": "high",
          "agora_uid": "3000",
          "agora_token": "<avatar_rtc_token>"
        }
      }
    }
  }'
```

`agent_rtc_uid`, the user UID in `remote_rtc_uids`, and `avatar.params.agora_uid` must all be different. Mint a separate token for each.

### What changes versus a voice-only Agora agent

| Concern                  | Voice-only Agora agent         | With LiveAvatar                                         |
| ------------------------ | ------------------------------ | ------------------------------------------------------- |
| Channel participants     | User + agent                   | User + agent + avatar                                   |
| Where TTS audio surfaces | Published by the agent         | Forwarded to LiveAvatar; avatar publishes audio + video |
| Tokens to mint           | Agent + user                   | Agent + user + avatar                                   |
| TTS sample rate          | Vendor default                 | Locked to 24 kHz                                        |
| Frontend rendering       | Audio-only subscribe           | Must also subscribe to the avatar UID's video track     |
| Billing                  | Agora minutes + your inference | Agora minutes + your inference + LiveAvatar minutes     |

## Concurrency and limits

Concurrent sessions are capped by the lower of your Agora Conversational AI limit and your LiveAvatar plan limit. Provision both sides before scaling load tests.

## Resources

<CardGroup cols={2}>
  <Card title="Agora — LiveAvatar by HeyGen" icon="book" href="https://docs.agora.io/en/conversational-ai/models/avatar/heygen">
    Upstream Agora reference for the LiveAvatar avatar provider.
  </Card>

  <Card title="Agora Conversational AI Engine" icon="book" href="https://docs.agora.io/en/conversational-ai/overview/product-overview">
    Product overview of the Agora pipeline LiveAvatar plugs into.
  </Card>
</CardGroup>