Tavus plugin for LiveKit Agents

Support for the Tavus virtual avatar.

See the Tavus integration docs for more information.

Installation

npm install @livekit/agents-plugin-tavus

Pre-requisites

You'll need an API key from Tavus. It can be set as an environment variable: TAVUS_API_KEY

Avatar emotion

Once the avatar has joined the room, set its facial emotion with setEmotion. The avatar keeps it until the next call.

start() returns before the avatar joins the room, and an emotion sent before then is dropped, so wait for the avatar with waitForJoin() first.

const avatar = new tavus.AvatarSession({ faceId: '...' });
await avatar.start(session, ctx.room);
await avatar.waitForJoin();

await avatar.setEmotion('happiness');

To let the LLM choose the emotion, wrap it in a tool:

const setEmotion = llm.tool({
  description: 'Set the facial emotion of your avatar.',
  parameters: z.object({ emotion: z.enum(tavus.EMOTIONS) }),
  execute: async ({ emotion }) => avatar.setEmotion(emotion),
});

Full Example

Find a complete working example here. The agent sets the avatar's emotion through a setEmotion tool as the mood of the conversation changes.

Set TAVUS_API_KEY to get up and running. TAVUS_FACE_ID and TAVUS_PAL_ID are optional; without them the stock pal is used.