LiveKit Agent

Prerequisites

Make sure you have the following before starting:

LiveKit Voice Assistant App (Python or Node.js)

Your own existing application.
Or follow the LiveKit Voice AI quickstart to create one (same guide for Python and Node.js).

We recommend using Phoenix-3 PRO faces, which are optimized for low-latency, real-time applications.

Integration Guide

Step 1: Setup and Authentication

Install the plugin:

Python
Node.js

pip install "livekit-agents[tavus]~=1.0"

npm install @livekit/agents @livekit/agents-plugin-tavus

Set TAVUS_API_KEY in your .env file. Use the same value as your Tavus API key from Authentication.

Step 2: Add an Avatar to your Agent

In your LiveKit app, create an avatar session alongside your AgentSession:

Python
Node.js / TypeScript

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

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) }));

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

replica_id / replicaId and persona_id / personaId are still accepted as deprecated aliases for face_id / pal_id.

Try out the integration using this sample code.

​Prerequisites

​Integration Guide

Prerequisites

Integration Guide