Skip to main content

​
AvatarSession

agenthuman.AvatarSession(
    avatar="avat_xxxxxxxxxxxxxxxxxxxxxxxx",
    aspect_ratio="4:3"
)

​
Constructor Parameters

ParameterTypeRequiredDescription
avatarstringNoAvatar ID or image URL. Falls back to AGENTHUMAN_AVATAR env var, then a default avatar
aspect_ratiostringNoVideo aspect ratio: '4:3', '3:4' or '1:1'. Defaults to '4:3'
api_keystringNoAgent Human API key. Falls back to AGENTHUMAN_API_KEY env var
avatar_participant_identitystringNoLiveKit identity for the avatar participant (default: 'agenthuman-avatar-agent')
avatar_participant_namestringNoLiveKit 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
)
ParameterTypeRequiredDescription
agent_sessionAgentSessionYesThe active LiveKit AgentSession
roomrtc.RoomYesThe LiveKit room from ctx.room
livekit_urlstringNoOverride for LIVEKIT_URL
livekit_api_keystringNoOverride for LIVEKIT_API_KEY
livekit_api_secretstringNoOverride 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

FieldTypeDescription
statestringCurrent avatar state (e.g. "connected", "disconnected")
reasonstringOptional reason string, present when state changes due to an error or explicit action