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

# Configuration

> AvatarSession parameters and options

## AvatarSession

```python theme={null}
agenthuman.AvatarSession(
    avatar="avat_xxxxxxxxxxxxxxxxxxxxxxxx",
    aspect_ratio="4:3"
)
```

### Constructor Parameters

| Parameter                     | Type   | Required | Description                                                                              |
| ----------------------------- | ------ | -------- | ---------------------------------------------------------------------------------------- |
| `avatar`                      | string | No       | Avatar ID or image URL. Falls back to `AGENTHUMAN_AVATAR` env var, then a default avatar |
| `aspect_ratio`                | string | No       | Video aspect ratio: `'4:3'`, `'3:4'` or `'1:1'`. Defaults to `'4:3'`                     |
| `api_key`                     | string | No       | Agent Human API key. Falls back to `AGENTHUMAN_API_KEY` env var                          |
| `avatar_participant_identity` | string | No       | LiveKit identity for the avatar participant (default: `'agenthuman-avatar-agent'`)       |
| `avatar_participant_name`     | string | No       | LiveKit display name for the avatar participant (default: `'agenthuman-avatar-agent'`)   |

## `start()` Method

```python theme={null}
await avatar.start(
    agent_session,
    room=ctx.room,
    livekit_url="wss://...",         # optional — reads LIVEKIT_URL env var
    livekit_api_key="...",           # optional — reads LIVEKIT_API_KEY env var
    livekit_api_secret="..."         # optional — reads LIVEKIT_API_SECRET env var
)
```

| Parameter            | Type           | Required | Description                       |
| -------------------- | -------------- | -------- | --------------------------------- |
| `agent_session`      | `AgentSession` | Yes      | The active LiveKit `AgentSession` |
| `room`               | `rtc.Room`     | Yes      | The LiveKit room from `ctx.room`  |
| `livekit_url`        | string         | No       | Override for `LIVEKIT_URL`        |
| `livekit_api_key`    | string         | No       | Override for `LIVEKIT_API_KEY`    |
| `livekit_api_secret` | string         | No       | Override for `LIVEKIT_API_SECRET` |

`start()` generates a LiveKit token for the avatar, creates the Agent Human session, and attaches the avatar's audio output to the room. It must be called before `session.start()`.

## `session.state` Events

The Agent Human server sends status updates to the room as LiveKit data packets on the `session.state` topic. You can listen for them on `ctx.room`:

```python theme={null}
from livekit import rtc

@ctx.room.on("data_received")
def on_data_received(data_packet: rtc.DataPacket) -> None:
    if data_packet.topic == "session.state":
        import json
        payload = json.loads(data_packet.data.decode("utf-8"))
        state  = payload.get("state")
        reason = payload.get("reason", "")
        print(f"Avatar state: {state} — {reason}")
```

### Payload Fields

| Field    | Type   | Description                                                                           |
| -------- | ------ | ------------------------------------------------------------------------------------- |
| `state`  | string | Current avatar state (e.g. `"connected"`, `"disconnected"`)                           |
| `reason` | string | Optional reason string, present when state changes due to an error or explicit action |