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.
Tavus demo
A video showcasing an educational AI agent that uses Tavus to create an interactive study partner.
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.2"
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
toecho
- Define a
transport
layer underlayers
, setting thetransport_type
inside tolivekit
.
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 agentsfrom livekit.agents import AgentSession, RoomOutputOptionsfrom livekit.plugins import tavusasync def entrypoint(ctx: agents.JobContext):session = AgentSession(# ... stt, llm, tts, etc.)avatar = tavus.AvatarSession(replica_id="...", # ID of the Tavus replica to usepersona_id="...", # ID of the Tavus persona to use (see preceding section for configuration details))# Start the avatar and wait for it to joinawait avatar.start(session, room=ctx.room)# Start your agent session with the userawait session.start(# ... room, agent, room_input_options, etc....)
Preview the avatar in the Agents Playground 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.
ID of the Tavus replica to use. See Replica and persona setup for details.
ID of the Tavus persona to use. See Replica and persona setup for details.
The name of the participant to use for the avatar.
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.
Agents Playground
A virtual workbench to test your avatar agent.
Frontend starter apps
Ready-to-use frontend apps with avatar support.