LiveKit Agent

With the LiveKit Agents integration, LiveKit runs your voice assistant in the room while Tavus renders the avatar. Create a persona whose layers include transport_type: livekit and the pipeline_mode value in Step 2, then start a tavus.AvatarSession with your replica_id and persona_id as in Step 3. 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 LiveKit Agents application, you can seamlessly add conversational avatars to real-time voice AI systems.

Prerequisites

Make sure you have the following before starting:

Tavus replica_id
- You can use Tavus’s stock Replicas or your own custom replica.

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

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 creates the persona via Create Persona.

Step 2: Configure Replica and Persona

Create a persona with LiveKit support using the Tavus API:

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

Replace <api-key> with your actual Tavus API key. You can generate one in the Developer Portal. See Authentication for how requests are authorized.
Set pipeline_mode to echo. That value is the persona’s pipeline mode for this integration; it is not the same as CVI conversation.echo app messages (which this LiveKit path does not support).
Set transport_type to livekit.

Save the persona_id from the API response.
Choose a replica from the Stock Library or browse available options on the Developer Portal.

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

Step 3: Add AvatarSession to AgentSession

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(
        replica_id="r90bbd427f71",
        persona_id="pcb7a34da5fe",
        # 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({
      replicaId: 'r90bbd427f71',
      personaId: 'pcb7a34da5fe',
      // 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
`replica_id` / `replicaId` (string)	ID of the Tavus replica to render and speak through
`persona_id` / `personaId` (string)	ID of the persona with the correct pipeline and transport configuration
`avatar_participant_name` / `avatarParticipantName` (string, optional)	Display name for the avatar participant in the room. Defaults to `Tavus-avatar-agent`

Try out the integration using this sample code.

​Prerequisites

​Integration Guide

Prerequisites

Integration Guide