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

# Quickstart

> Run a LiveKit Agents app with a Protoface avatar.

This sample uses Gemini Live. The same avatar flow applies to agents that use
separate STT, LLM, and TTS components.

Want more examples? Check out the [Quickstart Repo](https://github.com/protoface-ai/protoface-quickstart), which has examples you can easily clone and run in under 5 minutes.

## Prerequisites

* A Protoface API key from [app.protoface.com](https://app.protoface.com).
* A LiveKit project with `LIVEKIT_URL`, `LIVEKIT_API_KEY`, and
  `LIVEKIT_API_SECRET`.
* A Google Gemini API key for the sample realtime model: `GOOGLE_API_KEY`.

## 1. Install

```sh 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 `.env`:

```sh 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

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

Open [Agents Playground](https://agents-playground.livekit.io), connect it 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/video.
* `avatar.session_id` contains the `sess_...` ID.

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

## Next

<Columns cols={3}>
  <Card title="LiveKit Agents guide" href="/guides/livekit-agents" icon="radio">
    Configuration options and lifecycle details.
  </Card>

  <Card title="More Integrations" href="/guides/more-integrations" icon="blocks">
    Quickstarts for other platforms and SDKs.
  </Card>

  <Card title="Avatars" href="/guides/avatars" icon="user-round">
    Choose the avatar ID for your app.
  </Card>
</Columns>