Protoface virtual avatar integration guide

Available inPython

Overview

Protoface provides virtual avatars that can participate in live, interactive conversations. You can use the open source Protoface integration for LiveKit Agents to add virtual avatars to your voice AI app.

Quick reference

This section includes a basic usage example and some reference material. For links to more detailed documentation, see Additional resources.

Installation

uv add "livekit-agents[protoface]~=1.6"

Authentication

The Protoface plugin requires a Protoface API key .

Set PROTOFACE_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 protoface

server = AgentServer()

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

    avatar = protoface.AvatarSession(
        avatar_id="av_stock_001",  # ID of the Protoface avatar to use
    )

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

Preview the avatar in the Agent Console 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.

avatar_idstringDefault: av_stock_001

ID of the Protoface avatar to use. Learn more in the Protoface documentation .

api_keystring

Protoface API key. Defaults to the PROTOFACE_API_KEY environment variable.

max_duration_secondsint

Maximum session duration in seconds. Protoface applies the lower of this value and your account plan limit.

avatar_participant_identitystringDefault: protoface-avatar-agent

The identity of the participant to use for the avatar.

avatar_participant_namestringDefault: protoface-avatar-agent

The name of the participant to use for the avatar.

Additional resources

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

Python package

The livekit-plugins-protoface package on PyPI.

Plugin reference

Reference for the Protoface avatar plugin.

GitHub repo

View the source or contribute to the LiveKit Protoface avatar plugin.

Protoface docs

Protoface's full docs site.

Agent Console

A virtual workbench to test your avatar agent.

Frontend starter apps

Ready-to-use frontend apps with avatar support.