> ## 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 Face 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. Start a **`tavus.AvatarSession`** with your **`face_id`** as in Step 2.

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://maker.tavus.io/dev/faces" target="_blank">**Tavus `face_id`**</a>
  * You can use <a href="https://maker.tavus.io/dev/faces" target="_blank">Tavus's stock faces</a> or your own custom face.

- **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).

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

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

  <Step title="Step 2: Add an Avatar to your Agent">
    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(
                face_id="r90bbd427f71",
                # 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({
              faceId: 'r90bbd427f71',
              // 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                                                                            |
    | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
    | `face_id` / `faceId` (string)                                          | ID of the Tavus face to render and speak through.                                      |
    | `pal_id` / `palId` (string, optional)                                  | ID of a custom PAL. Defaults to a stock LiveKit PAL when omitted.                      |
    | `avatar_participant_name` / `avatarParticipantName` (string, optional) | Display name for the avatar participant in the room. Defaults to `Tavus-avatar-agent`. |

    <Note>
      `replica_id` / `replicaId` and `persona_id` / `personaId` are still accepted as deprecated aliases for `face_id` / `pal_id`.
    </Note>
  </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>