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.

Quick reference

This section includes a basic usage example and some reference material. For links to more detailed documentation, see Additional resources.

Installation

Install the plugin from PyPI:

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

Authentication

The Tavus plugin requires a Tavus API key.

Set TAVUS_API_KEY in your .env file.

Replica and persona setup

The Tavus plugin requires a Replica and a Persona to start an avatar session.

You can use any replica with the Tavus plugin, but must setup a persona with the following settings for full compatibility with LiveKit Agents:

• Set the pipeline_mode to echo
• Define a transport layer under layers, setting the transport_type inside to livekit.

Here is a simple curl command to create a persona with the correct settings using the Create Persona endpoint:

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

Copy your replica ID and persona ID for the following steps.

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 AgentSession, RoomOutputOptions
from livekit.plugins import tavus

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

   session = AgentSession(
      # ... stt, llm, tts, etc.
   )

   avatar = tavus.AvatarSession(
      replica_id="...",  # ID of the Tavus replica to use
      persona_id="...",  # ID of the Tavus persona 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=ctx.room,
      room_output_options=RoomOutputOptions(
         # Disable audio output to the room. The avatar plugin publishes audio separately.
         audio_enabled=False,
      ),
      # ... agent, room_input_options, etc....
   )

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 package

The livekit-plugins-tavus package on PyPI.

Plugin reference

Reference for the Tavus avatar plugin.

GitHub repo

View the source or contribute to the LiveKit Tavus avatar plugin.

Tavus docs

Tavus's full docs site.