Configuration

AvatarSession

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

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:

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

Getting Started

Pipecat

LiveKit

AvatarSession

Constructor Parameters

`start()` Method

`session.state` Events

Payload Fields

​AvatarSession

​Constructor Parameters

​start() Method

​session.state Events

​Payload Fields

AvatarSession

Constructor Parameters

`start()` Method

`session.state` Events

Payload Fields