Anam virtual avatar integration guide

Overview

Anam  provides lifelike avatars for realtime conversational AI. You can use the open source Anam integration for LiveKit Agents to enable seamless integration of Anam avatars into your voice AI app.

Installation

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

pnpm add @livekit/agents-plugin-anam

Authentication

The Anam plugin requires an Anam API key .

Set ANAM_API_KEY in your .env file.

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 anam

server = AgentServer()

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

   avatar = anam.AvatarSession(
      persona_config=anam.PersonaConfig(
         name="...",  # Name of the avatar to use.
         avatarId="...",  # ID of the avatar to use. See "Avatar setup" for 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 anam from '@livekit/agents-plugin-anam';

const session = new voice.AgentSession({
   // ... stt, llm, tts, etc.
});

const avatar = new anam.AvatarSession({
   personaConfig: {
      name: "...",  // Name of the avatar to use.
      avatarId: "...",  // ID of the avatar to use. See "Avatar setup" for 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.

Avatar setup

You can use stock avatars provided by Anam or create your own custom avatars using Anam Lab.

• Stock Avatars: Browse a collection of ready-to-use avatars in the Avatar Gallery .
• Custom Avatars: Create your own personalized avatar using Anam Lab .

To use a stock avatar, copy the avatar ID from the gallery and use it in your PersonaConfig. For custom avatars, create them in the lab and use the generated avatar ID.

Director notes

Director notes set a baseline expressive style for the avatar and control how strongly it performs that style.

To use director notes, set avatarModel to cara-4 and pass a DirectorNotes object to your PersonaConfig:

from livekit.plugins import anam

avatar = anam.AvatarSession(
   persona_config=anam.PersonaConfig(
      name="...",
      avatarId="...",
      avatarModel="cara-4",
      directorNotes=anam.DirectorNotes(
         presetStyle="warm",
         expressivity=0.7,
      ),
   ),
)

Choose a built-in style with presetStyle or provide your own with customStylePrompt. For the full list of preset styles, see Anam director notes .

Parameters

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

• name

  Required

  string

  #

  Name of the avatar to use. See Avatar setup for details.
• avatarId

  Required

  string

  #

  ID of the avatar to use. See Avatar setup for details.
• avatarModelstring

  #

  Avatar model version, for example cara-4. Required to use director notes. Omit to use the avatar's default model.
• directorNotesanam.DirectorNotes

  #

  Baseline expressive style for the avatar. Cara 4 only. See Director notes.
  • presetStylestring

    #

    A built-in expressive style, such as warm or happy. Mutually exclusive with customStylePrompt.
  • customStylePromptstring

    #

    A free-form expressive style prompt. Mutually exclusive with presetStyle.
  • expressivityfloat

    #

    How strongly the avatar performs the style, from 0 to 1. Omit to use Anam's default.

• video_widthintDefault: None

  #

  Output video width in pixels. Set together with video_height (both or neither). Supported pairs are model-dependent, and Anam rejects an unsupported pair with an HTTP 400.
• video_heightintDefault: None

  #

  Output video height in pixels. Set together with video_width.

Additional resources

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

Python plugin

ReferenceGitHubPyPI

Node.js plugin

ReferenceGitHubNPM

Anam API docs

Anam's LiveKit integration docs.

Agent Console

A virtual workbench to test your avatar agent.

Frontend starter apps

Ready-to-use frontend apps with avatar support.