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-clientUse 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),
});| Option | Type | Default | Meaning |
|---|---|---|---|
token | () => Promise<{ server_url: string; participant_token: string }> | Required | Calls your backend route. Runs right before joining, so the token is never stale. |
clientTools | Record<string, (args) => unknown | Promise<unknown>> | {} | One handler per declared tool; see Client tools. |
onStatusChange | (status) => void | Unset | connecting, ready, ending, ended; see Status. |
onModeChange | (mode) => void | Unset | listening, thinking, speaking; see Agent mode. |
onMessage | (message) => void | Unset | Transcript updates; see Transcripts. |
onWarning | ({ cause, seconds_left }) => void | Unset | See Warnings. |
onEnd | ({ reason }) => void | Unset | Called once; see End reasons. |
onError | (error: AgentSessionError) => void | Unset | Problems that don't end the call, such as a failed tool handler. |
onAudioBlocked | () => void | Unset | The browser blocked the agent's audio; show a button that calls startAudio(). |
microphone | boolean | MediaTrackConstraints | true | Microphone settings, or false to join muted. |
audio | boolean | true | Plays 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
| Member | What 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, mode | The current status and agent mode. |
sessionId | The session_id of the call. |
room | The 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:
code | Meaning |
|---|---|
TOKEN_FETCH_FAILED | Your token function threw or returned something else. |
CREDENTIALS_EXPIRED | The token was used after expires_at; see Response. |
CONNECTION_FAILED | The call couldn't connect; see Troubleshooting. |
AGENT_UNAVAILABLE | The 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_DENIED | The microphone was refused or isn't available. |
CLIENT_TOOL_FAILED | A tool handler threw or timed out. Reported through onError; the call goes on, and the agent has told the user. |
CLIENT_TOOL_NOT_HANDLED | The 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.