Realtime quickstart

Protoface Realtime turns an agent’s audio into live avatar video. This sample uses Gemini Live, and the same avatar flow applies to agents built from separate STT, LLM, and TTS components. For more examples you can clone and run, see the quickstart repo.

Prerequisites

A Protoface API key from app.protoface.com, covered in Authentication.
A LiveKit project with LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET.
A Google Gemini API key for the sample realtime model, set as GOOGLE_API_KEY.

1. Install

python -m venv .venv
source .venv/bin/activate
pip install livekit-plugins-protoface livekit-plugins-google python-dotenv

2. Set environment variables

Create a .env file:

LIVEKIT_URL="wss://your-project.livekit.cloud"
LIVEKIT_API_KEY="..."
LIVEKIT_API_SECRET="..."

PROTOFACE_API_KEY="sk_live_..."
PROTOFACE_AVATAR_ID="av_stock_001"

GOOGLE_API_KEY="..."

3. Add the avatar

Create agent.py:

import os

from dotenv import load_dotenv
from livekit.agents import (
    Agent,
    AgentServer,
    AgentSession,
    JobContext,
    TurnHandlingOptions,
    cli,
    room_io,
)
from livekit.plugins import google, protoface

load_dotenv()

server = AgentServer()
AGENT_INSTRUCTIONS = (
    "You are a friendly AI avatar. "
    "Keep responses natural, concise, and conversational."
)


@server.rtc_session()
async def entrypoint(ctx: JobContext):
    session = AgentSession(
        llm=google.realtime.RealtimeModel(
            model=os.getenv("GEMINI_MODEL", "gemini-3.1-flash-live-preview"),
            voice=os.getenv("GEMINI_VOICE", "Charon"),
        ),
        turn_handling=TurnHandlingOptions(
            interruption={"resume_false_interruption": False},
        ),
    )

    avatar = protoface.AvatarSession(
        avatar_id=os.getenv("PROTOFACE_AVATAR_ID", protoface.DEFAULT_STOCK_AVATAR_ID),
    )
    await avatar.start(session, room=ctx.room)

    await session.start(
        agent=Agent(instructions=AGENT_INSTRUCTIONS),
        room=ctx.room,
        # Let Protoface publish the assistant audio.
        room_options=room_io.RoomOptions(audio_output=False),
    )


if __name__ == "__main__":
    cli.run_app(server)

4. Run the agent

python agent.py start

Open Agents Playground, connect to your LiveKit project, join the room, and talk to the agent.

Expected result

A protoface-avatar-agent participant joins the same LiveKit room.
The avatar publishes audio and video.
avatar.session_id contains the sess_... ID, which moves through queued, starting, and running before the first frame.
The session ends when the agent stops, or on await avatar.aclose().

Troubleshooting

Symptom	Check
`Protoface API key is required`	Set `PROTOFACE_API_KEY` or pass `api_key` to `AvatarSession`.
`livekit_url, livekit_api_key, and livekit_api_secret must be set`	Set the three `LIVEKIT_*` variables or pass them to `avatar.start(...)`.
No avatar participant appears	Confirm the agent connected to the same LiveKit room as the Playground.
Avatar joins but stays silent	Confirm the agent can produce speech and the avatar participant joined the same room.

LiveKit Agents covers plugin options, the session lifecycle, and the REST endpoints underneath. Avatars shows how to replace the stock avatar with your own.

Inference

Realtime

Account

Reference

Realtime quickstart

Prerequisites

1. Install

2. Set environment variables

3. Add the avatar

4. Run the agent

Expected result

Troubleshooting

​Prerequisites

​1. Install

​2. Set environment variables

​3. Add the avatar

​4. Run the agent

​Expected result

​Troubleshooting

Prerequisites

1. Install

2. Set environment variables

3. Add the avatar

4. Run the agent

Expected result

Troubleshooting