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:
| Status | Meaning |
|---|---|
connecting | Fetching the token and joining the call. |
ready | The agent has joined the call. |
ending | The call is closing. |
ended | The 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:
| Mode | Meaning |
|---|---|
listening | Waiting for the user, or hearing them speak. |
thinking | Working on a reply or waiting for a client tool. |
speaking | Talking. The user can interrupt by speaking. |
Transcripts
onMessage delivers what the user and the agent said, as text:
| Field | Type | Meaning |
|---|---|---|
id | string | Stays the same while one message is being updated. |
role | user or agent | Who said it. |
text | string | The text so far. |
final | boolean | true 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:
cause | When it fires | seconds_left |
|---|---|---|
max_duration | 60 seconds before your plan's maximum call length. | 60 |
credits | When 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.
| Group | reason | Meaning | Charged |
|---|---|---|---|
| User | user_left | The user hung up or closed the page. | Minutes started |
| User | user_never_joined | The token wasn't used before expires_at. | Nothing |
| Agent | agent_ended | The agent ended the call with end_call. | Minutes started |
| Agent | idle_timeout | Nobody spoke for your plan's idle time. | Minutes started |
| Limits | max_duration | The call reached your plan's maximum length. | Minutes started |
| Limits | credits_exhausted | The account couldn't pay for the next minute. | Minutes started |
| Limits | concurrency_limit | Too many calls were live when this one joined. | Nothing |
| Limits | account_disabled | Voice Agent is turned off for the account. | Minutes started |
| Errors | agent_error | The agent failed. | Minutes started |
| Errors | platform_error | HUMAIN 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:
| What | How |
|---|---|
| Agent mode | Participant attribute lk.agent.state on the agent: initializing, listening, thinking, or speaking. |
| Transcripts | Text streams on topic lk.transcription; attribute lk.transcription_final marks final text and lk.segment_id identifies a message. |
| Send text | A text stream on topic lk.chat. |
| Warnings and end reason | Data messages from the agent on topic humain.session (below). |
| Update context, interrupt | Data messages to the agent on topic humain.session (below). |
| Client tools | RPC 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.