Skip to main content
If your voice agent runs on LiveKit Agents, livekit-plugins-protoface is an easy way to add an avatar. It opens a Protoface session and joins the avatar to your room, then streams your agent’s audio to it. If you’re not using LiveKit, Protoface also integrates with many more platforms and SDKs. See More Integrations.

​
Install

pip install livekit-plugins-protoface

​
Basic usage

from livekit.plugins import protoface

avatar = protoface.AvatarSession(avatar_id="av_stock_001")
await avatar.start(session, room=ctx.room)
Start the avatar before session.start(...): 
await session.start(
    agent=agent,
    room=ctx.room,
)
After the avatar starts, the plugin routes agent audio through a LiveKit DataStream output addressed to the avatar participant.

​
Token handling

AvatarSession.start(...) uses your LiveKit API key and secret inside the agent process to mint a short-lived avatar room token. Protoface receives that token as worker_token; it never receives your LiveKit API secret.

​
Configuration

Set these in the agent environment.
VariableRequiredUsed for
PROTOFACE_API_KEYyesAuthenticates calls to Protoface.
PROTOFACE_API_URLnoOverrides https://api.protoface.com.
LIVEKIT_URLyesThe LiveKit server the avatar joins.
LIVEKIT_API_KEYyesUsed locally to mint the avatar room token.
LIVEKIT_API_SECRETyesUsed locally to mint the avatar room token. Do not expose it to clients.
Or pass them directly: 
avatar = protoface.AvatarSession(
    avatar_id="av_stock_001",
    api_key="sk_live_...",
)

await avatar.start(
    session,
    room=ctx.room,
    livekit_url="wss://your-project.livekit.cloud",
    livekit_api_key="...",
    livekit_api_secret="...",
)

​
AvatarSession options

OptionPurpose
avatar_idAvatar to render. Use an ID from the dashboard or /v1/avatars.
api_keyProtoface API key. Defaults to PROTOFACE_API_KEY.
api_urlProtoface API base URL. Defaults to PROTOFACE_API_URL or https://api.protoface.com.
avatar_participant_identityLiveKit identity for the avatar participant.
avatar_participant_nameLiveKit display name for the avatar participant.
max_duration_secondsOptional upper bound for the Protoface session.
conn_optionsLiveKit Agents connection timeout and retry options.
After avatar.start(...) succeeds, avatar.session_id contains the Protoface session ID.

​
Lifecycle

Call await avatar.start(session, room=ctx.room) before session.start(...). Call await avatar.aclose() if you need to stop the avatar explicitly.

​
Next

Quickstart

Run a complete sample agent.

More Integrations

Quickstarts for other platforms and SDKs.

Avatars

Choose the avatar ID for your app.