Voice Agent

Session lifecycle

Track a Voice Agent call from connecting to ended, show live transcripts and warnings, send text during the call, and handle every end reason.

The browser SDK reports the call through callbacks on AgentSession.start(). The full option list is on the Browser SDK page.

Status

onStatusChange reports where the call is:

StatusMeaning
connectingFetching the token and joining the call.
readyThe agent has joined the call.
endingThe call is closing.
endedThe call is over. onEnd has been called with the end reason.

Agent mode

onModeChange reports what the agent is doing while the call is ready:

ModeMeaning
listeningWaiting for the user, or hearing them speak.
thinkingWorking on a reply or waiting for a client tool.
speakingTalking. The user can interrupt by speaking.

Transcripts

onMessage delivers what the user and the agent said, as text:

FieldTypeMeaning
idstringStays the same while one message is being updated.
roleuser or agentWho said it.
textstringThe text so far.
finalbooleantrue once the text won't change.

Replace the text of a message with the same id until final is true, then keep it. Agent text arrives in step with the agent's speech.

Methods

sendText(), interrupt(), updateContext(), setMicMuted(), and end() are on the Browser SDK page.

Warnings

onWarning fires before the call is ended for you, so you can tell the user:

causeWhen it firesseconds_left
max_duration60 seconds before your plan's maximum call length.60
creditsWhen your account's credit covers only the current minute.Seconds until that minute ends.

End reasons

onEnd receives { reason }. The same values appear in usage records.

GroupreasonMeaningCharged
Useruser_leftThe user hung up or closed the page.Minutes started
Useruser_never_joinedThe token wasn't used before expires_at.Nothing
Agentagent_endedThe agent ended the call with end_call.Minutes started
Agentidle_timeoutNobody spoke for your plan's idle time.Minutes started
Limitsmax_durationThe call reached your plan's maximum length.Minutes started
Limitscredits_exhaustedThe account couldn't pay for the next minute.Minutes started
Limitsconcurrency_limitToo many calls were live when this one joined.Nothing
Limitsaccount_disabledVoice Agent is turned off for the account.Minutes started
Errorsagent_errorThe agent failed.Minutes started
Errorsplatform_errorHUMAIN Voice failed. Contact support with the session_id.Minutes started

Before idle_timeout, max_duration, credits_exhausted, and account_disabled, the agent says a short goodbye. If the connection drops without an end reason, the browser SDK reports platform_error.

New reasons may be added; show a generic message for a value you don't recognize. Minute charges are explained in Limits and billing.

Without the SDK

Any LiveKit client can join with server_url and participant_token; see LiveKit clients. The agent uses LiveKit's standard agent signals plus one data topic of its own:

WhatHow
Agent modeParticipant attribute lk.agent.state on the agent: initializing, listening, thinking, or speaking.
TranscriptsText streams on topic lk.transcription; attribute lk.transcription_final marks final text and lk.segment_id identifies a message.
Send textA text stream on topic lk.chat.
Warnings and end reasonData messages from the agent on topic humain.session (below).
Update context, interruptData messages to the agent on topic humain.session (below).
Client toolsRPC method client_tool_call; see Client tools.

Messages on humain.session are UTF-8 JSON:

{ "type": "session_warning", "cause": "max_duration", "seconds_left": 60 }
{ "type": "session_end", "reason": "max_duration" }
{ "type": "context_update", "context": { "page": "checkout" } }
{ "type": "interrupt" }

The agent sends session_end just before it closes the room. If the connection drops without it, treat the call as ended.

On this page