> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tavus.io/llms.txt
> Use this file to discover all available pages before exploring further.

# LiveKit Agent

> Integrate a Tavus Replica into LiveKit as the conversational video avatar.

With the LiveKit Agents integration, **LiveKit** runs your voice assistant in the room while **Tavus** renders the avatar. Create a **persona** whose layers include **`transport_type: livekit`** and the **`pipeline_mode`** value in Step 2, then start a **`tavus.AvatarSession`** with your **`replica_id`** and **`persona_id`** as in Step 3.

Tavus enables AI developers to create realistic video avatars powered by state-of-the-art speech synthesis, perception, and rendering pipelines. Through its integration with the <a href="https://docs.livekit.io/agents/" target="_blank">**LiveKit Agents**</a> application, you can seamlessly add conversational avatars to real-time voice AI systems.

## Prerequisites

Make sure you have the following before starting:

* <a href="https://platform.tavus.io/replicas" target="_blank">**Tavus `replica_id`**</a>
  * You can use <a href="https://platform.tavus.io/replicas" target="_blank">Tavus's stock Replicas</a> or your own custom replica.

- **LiveKit Voice Assistant App** (Python or Node.js)
  * Your own existing application.
  * Or follow the <a href="https://docs.livekit.io/agents/start/voice-ai/" target="_blank">LiveKit Voice AI quickstart</a> to create one (same guide for Python and Node.js).

## Integration Guide

<Steps>
  <Step title="Step 1: Setup and Authentication">
    1. Install the plugin:

    <Tabs>
      <Tab title="Python">
        ```bash theme={null}
        pip install "livekit-agents[tavus]~=1.0"
        ```
      </Tab>

      <Tab title="Node.js">
        ```bash theme={null}
        npm install @livekit/agents @livekit/agents-plugin-tavus
        ```
      </Tab>
    </Tabs>

    2. Set `TAVUS_API_KEY` in your `.env` file. Use the same value as your Tavus API key from [Authentication](/api-reference/authentication). Step 2 creates the persona via [Create Persona](/api-reference/personas/create-persona).
  </Step>

  <Step title="Step 2: Configure Replica and Persona">
    1. Create a persona with LiveKit support using the Tavus API:

    ```bash {7, 10} theme={null}
    curl --request POST \
      --url https://tavusapi.com/v2/personas \
      -H "Content-Type: application/json" \
      -H "x-api-key: <api-key>" \
      -d '{
      "persona_name": "Customer Service Agent",
      "pipeline_mode": "echo",
      "layers": {
        "transport": {
                "transport_type": "livekit"
        }
      }
    }'
    ```

    <Note>
      * Replace `<api-key>` with your actual Tavus API key. You can generate one in the <a href="https://platform.tavus.io/api-keys" target="_blank">Developer Portal</a>. See [Authentication](/api-reference/authentication) for how requests are authorized.
      * Set `pipeline_mode` to `echo`. That value is the **persona’s pipeline mode** for this integration; it is not the same as CVI **`conversation.echo`** app messages (which this LiveKit path does not support).
      * Set `transport_type` to `livekit`.
    </Note>

    2. Save the `persona_id` from the API response.
    3. Choose a replica from the [Stock Library](/sections/replica/stock-replicas) or browse available options on the <a href="https://platform.tavus.io/replicas" target="_blank" rel="noopener noreferrer">Developer Portal</a>.

    <Tip>
      We recommend using **Phoenix-3 PRO Replicas**, which are optimized for low-latency, real-time applications.
    </Tip>
  </Step>

  <Step title="Step 3: Add AvatarSession to AgentSession">
    In your LiveKit app, create an avatar session alongside your `AgentSession`:

    <Tabs>
      <Tab title="Python">
        ```python {12-16, 18} theme={null}
        from livekit import agents
        from livekit.agents import AgentSession, RoomOutputOptions
        from livekit.plugins import tavus

        async def entrypoint(ctx: agents.JobContext):
            await ctx.connect()

            session = AgentSession(
                # Add STT, LLM, TTS, and other components here
            )

            avatar = tavus.AvatarSession(
                replica_id="r90bbd427f71",
                persona_id="pcb7a34da5fe",
                # Optional: avatar_participant_name="Tavus-avatar-agent"
            )

            await avatar.start(session, room=ctx.room)

            await session.start(
                room=ctx.room,
                room_output_options=RoomOutputOptions(
                    audio_enabled=False  # Tavus handles audio separately
                )
            )
        ```
      </Tab>

      <Tab title="Node.js / TypeScript">
        ```typescript {15-19, 22} theme={null}
        import { type JobContext, WorkerOptions, cli, defineAgent, voice } from '@livekit/agents';
        import * as tavus from '@livekit/agents-plugin-tavus';
        import { fileURLToPath } from 'node:url';

        export default defineAgent({
          entry: async (ctx: JobContext) => {
            await ctx.connect();

            const session = new voice.AgentSession({
              // Add STT, LLM, TTS, and other components here
            });

            const avatar = new tavus.AvatarSession({
              replicaId: 'r90bbd427f71',
              personaId: 'pcb7a34da5fe',
              // Optional: avatarParticipantName: 'Tavus-avatar-agent'
            });

            // Start avatar first so it joins the room before the session pipes audio out
            await avatar.start(session, ctx.room);

            await session.start({
              agent: new voice.Agent({ instructions: 'You are a helpful assistant.' }),
              room: ctx.room,
            });
          },
        });

        cli.runApp(new WorkerOptions({ agent: fileURLToPath(import.meta.url) }));
        ```
      </Tab>
    </Tabs>

    | Parameter                                                              | Description                                                                           |
    | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
    | `replica_id` / `replicaId` (string)                                    | ID of the Tavus replica to render and speak through                                   |
    | `persona_id` / `personaId` (string)                                    | ID of the persona with the correct pipeline and transport configuration               |
    | `avatar_participant_name` / `avatarParticipantName` (string, optional) | Display name for the avatar participant in the room. Defaults to `Tavus-avatar-agent` |
  </Step>
</Steps>

<Note>
  Try out the integration using this <a href="https://github.com/livekit/agents/tree/main/examples/avatar_agents/tavus" target="_blank">sample code</a>.
</Note>