> ## Documentation Index
> Fetch the complete documentation index at: https://docs.protoface.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Realtime quickstart

> Add a live avatar to a LiveKit agent.

<div
  style={{
border: "1px solid rgba(12, 13, 14, 0.10)",
borderRadius: "12px",
marginBottom: "2rem",
marginTop: "0.5rem",
overflow: "hidden"
}}
>
  <img src="https://mintcdn.com/protoface/nbz_dO5dzz6bYKFl/images/home/welcome-avatar-grid.webp?fit=max&auto=format&n=nbz_dO5dzz6bYKFl&q=85&s=de5da815fee7521a505fbd2eca9a48cb" alt="Protoface avatars displayed as realtime video tiles" style={{ display: "block", height: "auto", margin: 0, width: "100%" }} width="1600" height="900" data-path="images/home/welcome-avatar-grid.webp" />
</div>

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](https://github.com/protoface-ai/protoface-quickstart).

## Prerequisites

* A Protoface API key from [app.protoface.com](https://app.protoface.com),
  covered in [Authentication](/guides/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

```bash theme={null}
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:

```bash theme={null}
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`:

```python theme={null}
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

```bash theme={null}
python agent.py start
```

Open [Agents Playground](https://agents-playground.livekit.io), 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](/guides/livekit-agents) covers plugin options, the
session lifecycle, and the REST endpoints underneath.
[Avatars](/guides/avatars) shows how to replace the stock avatar with
your own.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.