Configuration - Documentation

AvatarSession

from livekit.plugins import agenthuman

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

Constructor Parameters

Provide at most one of avatar_id and avatar_image_url (directly or through their environment variables). With neither, a public stock avatar is used.

Parameter	Type	Required	Description
`avatar_id`	string	No	Avatar ID (`avat_...`). Falls back to `AGENTHUMAN_AVATAR_ID`, then to a public stock avatar (`avat_01KMZJ3YN6BR83KR1FHP8VTHNX`)
`avatar_image_url`	string	No	Publicly accessible image to animate instead of an avatar ID. Falls back to `AGENTHUMAN_IMAGE_URL`
`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`
`api_url`	string	No	Agent Human API URL. Falls back to `AGENTHUMAN_API_URL`, then `https://api.agenthuman.com/v1`
`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'`)
`conn_options`	`APIConnectOptions`	No	Timeout and retries for the Agent Human API call. Server errors are retried, client errors (4xx) are not

Any other keyword arguments are sent with the session request.

`start()` Method

session_id = 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 routes your agent’s audio output to the avatar. It returns the Agent Human session ID (also available as avatar.session_id). Call it before session.start().

Interruptions

The avatar tells your agent when it actually starts and stops speaking each reply. When the user interrupts, it stops within about a second (finishing the word it is on) and reports how much of the reply was heard, so your agent keeps only that part of the transcript. Configure the agent session like this:

from livekit.agents import AgentSession, TurnHandlingOptions

session = AgentSession(
    # ... your STT, LLM, TTS config
    turn_handling=TurnHandlingOptions(
        interruption={"mode": "vad", "resume_false_interruption": False},
    ),
)

Setting	Why
`"mode": "vad"`	Interrupt on the user’s voice activity. LiveKit’s adaptive detection (the default in `dev` mode) can classify speech over the avatar as a backchannel (“mm-hm”) and ignore it, so the avatar keeps talking
`"resume_false_interruption": False`	The avatar can’t pause and resume a reply

`session.state` Events

The Agent Human server sends status updates to the room as LiveKit data packets on the session.state topic. The plugin logs them; you can also listen for them on ctx.room:

import json
from livekit import rtc

@ctx.room.on("data_received")
def on_data_received(data_packet: rtc.DataPacket) -> None:
    if data_packet.topic == "session.state":
        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	`"ready"` (the avatar is in the room and rendering), `"expired"` (the session reached its time limit) or `"ended"`
`reason`	string	Set when the session ends: `"expiry"`, `"user"` or `"server"`