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