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

# LiveKit Agents

> Use the Protoface avatar plugin in a LiveKit Agents app.

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](/guides/more-integrations).

## Install

```sh theme={null}
pip install livekit-plugins-protoface
```

## Basic usage

```python theme={null}
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(...)`:

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

| Variable             | Required | Used for                                                                 |
| -------------------- | -------- | ------------------------------------------------------------------------ |
| `PROTOFACE_API_KEY`  | yes      | Authenticates calls to Protoface.                                        |
| `PROTOFACE_API_URL`  | no       | Overrides `https://api.protoface.com`.                                   |
| `LIVEKIT_URL`        | yes      | The LiveKit server the avatar joins.                                     |
| `LIVEKIT_API_KEY`    | yes      | Used locally to mint the avatar room token.                              |
| `LIVEKIT_API_SECRET` | yes      | Used locally to mint the avatar room token. Do not expose it to clients. |

Or pass them directly:

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

| Option                        | Purpose                                                                                 |
| ----------------------------- | --------------------------------------------------------------------------------------- |
| `avatar_id`                   | Avatar to render. Use an ID from the dashboard or `/v1/avatars`.                        |
| `api_key`                     | Protoface API key. Defaults to `PROTOFACE_API_KEY`.                                     |
| `api_url`                     | Protoface API base URL. Defaults to `PROTOFACE_API_URL` or `https://api.protoface.com`. |
| `avatar_participant_identity` | LiveKit identity for the avatar participant.                                            |
| `avatar_participant_name`     | LiveKit display name for the avatar participant.                                        |
| `max_duration_seconds`        | Optional upper bound for the Protoface session.                                         |
| `conn_options`                | LiveKit 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

<Columns cols={3}>
  <Card title="Quickstart" href="/quickstart" icon="rocket">
    Run a complete sample agent.
  </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>