Tavus virtual avatar integration guide

Overview

Tavus  provides hyper-realistic interactive avatars for conversational video AI agents. You can use the open source Tavus integration for LiveKit Agents to add virtual avatars to your voice AI app.

Installation

uv add "livekit-agents[tavus]~=1.5"

pnpm add @livekit/agents-plugin-tavus

Authentication

The Tavus plugin requires a Tavus API key .

Set TAVUS_API_KEY in your .env file.

Faces and PALs

A Tavus avatar combines a face  and a Personified Application Layer (PAL ). The face is the on-screen likeness and voice. The PAL is the conversational configuration: it sets the agent's behavior and the LiveKit transport, and carries a default face. The face overrides the PAL's default face when you set one. Choose each with the face_id and pal_id parameters, or omit either to fall back to a default.

Using faces

By default, the avatar uses the PAL's default face. To use a specific appearance, set face_id to a stock or custom face:

• Browse Tavus's stock faces  and copy the ID of one you like.
• Train a custom face  from a short video or an image.

Using PALs

By default, the plugin uses a stock PAL already configured for LiveKit Agents, which covers most apps. To define your own conversational configuration, create a PAL and pass its ID as pal_id. A PAL used with LiveKit Agents must set pipeline_mode to echo and define a livekit transport layer. The following curl command creates one using the Create PAL endpoint :

curl --request POST \
  --url https://tavusapi.com/v2/pals \
  -H "Content-Type: application/json" \
  -H "x-api-key: <api-key>" \
  -d '{
    "pal_name": "My PAL",
    "default_face_id": "<face-id>",
    "pipeline_mode": "echo",
    "layers": {
        "transport": {
            "transport_type": "livekit"
        }
    }
}'

In Node.js, you can also create a PAL in code with TavusAPI:

import { TavusAPI } from '@livekit/agents-plugin-tavus';

const tavus = new TavusAPI(); // reads TAVUS_API_KEY
const palId = await tavus.createPal({ defaultFaceId: '<face-id>' });

Usage

Use the plugin in an AgentSession. For example, you can use this avatar in the Voice AI quickstart.

from livekit import agents
from livekit.agents import AgentServer, AgentSession
from livekit.plugins import tavus

server = AgentServer()

@server.rtc_session(agent_name="my-agent")
async def my_agent(ctx: agents.JobContext):
   session = AgentSession(
      # ... stt, llm, tts, etc.
   )

   avatar = tavus.AvatarSession(
      # Both are optional. Omit to use a default stock PAL.
      face_id="...",  # ID of the Tavus face to use
      pal_id="...",  # ID of the Tavus PAL to use (see preceding section for configuration details)
   )

   # Start the avatar and wait for it to join
   await avatar.start(session, room=ctx.room)

   # Start your agent session with the user
   await session.start(
      # ... room, agent, room_options, etc....
   )

import { voice } from '@livekit/agents';
import * as tavus from '@livekit/agents-plugin-tavus';

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

const avatar = new tavus.AvatarSession({
  // Both are optional. Omit to use a default stock PAL.
  faceId: '...', // ID of the Tavus face to use
  palId: '...', // ID of the Tavus PAL to use (see preceding section for configuration details)
});

// Start the avatar and wait for it to join
await avatar.start(session, room);

// Start your agent session with the user
await session.start(
    // ... room, agent, room_options, etc.
);

Preview the avatar in the Agent Console or a frontend starter app that you build.

Parameters

This section describes some of the available parameters. See the plugin reference for a complete list of all available parameters.

Additional resources

The following resources provide more information about using Tavus with LiveKit Agents.

Python plugin

ReferenceGitHubPyPI

Node.js plugin

ReferenceGitHubNPM

Tavus docs

Tavus's full docs site.

Agent Console

A virtual workbench to test your avatar agent.

Frontend starter apps

Ready-to-use frontend apps with avatar support.