Skip to main content
By the end of this guide your existing LiveKit agent will run a full voice AI pipeline (STT → LLM → TTS) with an attached Avaluma avatar. You’ll use the hosted Avatar Server (api.avaluma.ai) – no GPU infrastructure of your own required. Prefer to self-host? The optional path is at the end.
1

Create a LiveKit agent

We recommend LiveKit’s Voice AI Quickstart Guide to set up your first LiveKit agent with Python >=3.11. If you already have a LiveKit agent on Python >=3.11, you can use that instead.
Node.js agents are not supported.
Make sure you can talk to your LiveKit agent in the LiveKit Playground before you continue and attach the avatar.

Voice AI Quickstart Guide

LiveKit’s guide for your first voice agent.

LiveKit Playground

Test your agent right in the browser.
2

Install the Avaluma plugin

Install the Avaluma LiveKit plugin in your agent’s Python environment.
LiveKit’s agent-starter-python repository uses uv.
pip install git+https://github.com/avaluma-ai/avaluma-livekit-plugin.git
3

Add the avatar to your agent

Add the following import at the top of your LiveKit agent’s Python file. In LiveKit’s agent-starter-python repo the file is called agent.py.
from avaluma_livekit_plugin import AvatarSession
In the same file, find await session.start and insert the following avatar setup block right before it:
# Avatar
avatar = AvatarSession(
    license_key="YOUR_AVALUMA_KEY",
    avatar_id="260218-Avaluma_Avatar_Kadda_v5",  # Avatar identifier without .hvia ("string" -> test stream)
    avatar_server_url="https://api.avaluma.ai",
)
# Start the avatar and wait for it to join
await avatar.start(room=ctx.room, agent_session=session)
Finally, adjust the AvatarSession arguments – in particular the license_key.
You can create a license key in the login area.
4

Test the avatar & agent in the LiveKit Playground

Start your agent as usual and test it directly in the LiveKit Agents Playground. This is the fastest and easiest way to see agent and avatar in action.Your avatar should appear in the video track and respond to your voice in real time.For integration into web and mobile apps, LiveKit provides SDKs and example projects – from React and JavaScript to Swift and Android.

LiveKit Playground

Test agent and avatar right in the browser.

LiveKit Frontend Docs

SDKs & examples for web, iOS, Android and more.

​
Self-hosting (optional)

You can also run the Avaluma Avatar Server yourself with Docker – fully on-prem, with no dependency on api.avaluma.ai. To do so, point avatar_server_url at your own container instead of https://api.avaluma.ai.

Self-hosting quickstart

Deploy the Avatar Server and LiveKit agent yourself with Docker – step by step.

​
Next steps

Embed your agent

Embed your avatar as a widget on your own website.

Help & examples

Example projects in the Examples repo. Questions? Email us at dev@avaluma.ai.