SDKs

Voice Agent browser SDK

Join a Voice Agent call from the browser with @humain-voice/agent, handle client tools, and react to status, transcripts, warnings, and end reasons.

@humain-voice/agent joins a Voice Agent call from a web page. It runs on livekit-client, which it shares with any LiveKit components on the page. It never sees your API key: it gets a token from your backend.

Install

npm install @humain-voice/[email protected] livekit-client

Use it from a bundled web app (Vite, Next.js, esbuild, and so on). The page needs microphone access, so serve it from localhost or over HTTPS.

Start a call

AgentSession.start(options) fetches a token, joins the call, turns on the microphone, and resolves once the call is ready. Call it from a click or tap so the browser allows audio:

import { AgentSession } from '@humain-voice/agent';

const call = await AgentSession.start({
  token: () => fetch('/agent-session', { method: 'POST' }).then((res) => res.json()),
  onStatusChange: (status) => console.log('status:', status),
  onEnd: ({ reason }) => console.log('ended:', reason),
});
OptionTypeDefaultMeaning
token() => Promise<{ server_url: string; participant_token: string }>RequiredCalls your backend route. Runs right before joining, so the token is never stale.
clientToolsRecord<string, (args) => unknown | Promise<unknown>>{}One handler per declared tool; see Client tools.
onStatusChange(status) => voidUnsetconnecting, ready, ending, ended; see Status.
onModeChange(mode) => voidUnsetlistening, thinking, speaking; see Agent mode.
onMessage(message) => voidUnsetTranscript updates; see Transcripts.
onWarning({ cause, seconds_left }) => voidUnsetSee Warnings.
onEnd({ reason }) => voidUnsetCalled once; see End reasons.
onError(error: AgentSessionError) => voidUnsetProblems that don't end the call, such as a failed tool handler.
onAudioBlocked() => voidUnsetThe browser blocked the agent's audio; show a button that calls startAudio().
microphoneboolean | MediaTrackConstraintstrueMicrophone settings, or false to join muted.
audiobooleantruePlays the agent's audio. Set false if you play it yourself, for example with LiveKit's RoomAudioRenderer.

If the call can't start, the promise rejects with an AgentSessionError and onEnd isn't called.

Methods and properties

MemberWhat it does
sendText(text)Sends a typed message. The agent answers as if the user had said it, and stops talking first if needed.
interrupt()Stops the agent's current reply.
updateContext(values)Tells the agent new facts for the rest of the call, such as the page the user opened. Same value types as variables.
setMicMuted(muted)Mutes or unmutes the microphone.
startAudio()Resumes blocked audio. Call it from a click.
end()Hangs up and resolves when the call is ended. The call ends with user_left.
status, modeThe current status and agent mode.
sessionIdThe session_id of the call.
roomThe underlying LiveKit Room, for LiveKit UI components or anything else LiveKit offers.

After the call ends, sendText(), interrupt(), updateContext(), and setMicMuted() do nothing and log a warning.

Errors

AgentSessionError has a code:

codeMeaning
TOKEN_FETCH_FAILEDYour token function threw or returned something else.
CREDENTIALS_EXPIREDThe token was used after expires_at; see Response.
CONNECTION_FAILEDThe call couldn't connect; see Troubleshooting.
AGENT_UNAVAILABLEThe agent didn't join within 20 seconds, or the call ended before it was ready. If endReason is unset and it keeps happening, contact support with the session_id.
MIC_PERMISSION_DENIEDThe microphone was refused or isn't available.
CLIENT_TOOL_FAILEDA tool handler threw or timed out. Reported through onError; the call goes on, and the agent has told the user.
CLIENT_TOOL_NOT_HANDLEDThe agent called a tool with no handler. Reported through onError.

When the call ended before it was ready, the error's endReason holds the end reason the agent sent, such as concurrency_limit or credits_exhausted. It's unset otherwise.

React

call.room works with LiveKit's React components and Agents UI:

<RoomContext.Provider value={call.room}>{/* control bar, visualizer, transcript */}</RoomContext.Provider>

If you add RoomAudioRenderer, pass audio: false so the agent isn't heard twice. See LiveKit clients.

On this page