Voice Agent

VoiceAgentClient manages a full-duplex WebSocket for real-time conversations. It handles microphone capture, audio playback, STT, LLM, TTS, and interruptions.

Basic usage

JavaScript (browser)
Python

import { VoiceAgentClient, VoiceStyle, Language } from '@lokutor/sdk';

// auth: called before every connect and reconnect. Your backend returns a fresh
// wst_ ticket from POST /ws-ticket (see Secure browser setup); the API key stays there.
const getTicket = async () =>
  (await fetch('/api/lokutor-ticket', { method: 'POST' }).then((r) => r.json())).ticket;

const client = new VoiceAgentClient({
  auth: getTicket,
  prompt: 'You are a helpful and friendly AI assistant.',
  voice: VoiceStyle.F1,
  language: Language.ENGLISH,
});

client.on('transcription', (text) => console.log('You:', text));
client.on('response', (text) => console.log('Agent:', text));
client.on('status', (status) => console.log('Status:', status));
client.on('error', (err) => console.error('Error:', err));

// Must be called inside a user gesture (button click)
await client.startManaged();

from lokutor import VoiceAgentClient, VoiceStyle, Language
import os

def on_transcription(text):
    print(f"You: {text}")

def on_response(text):
    print(f"Agent: {text}")

client = VoiceAgentClient(
    api_key=os.environ['LOKUTOR_API_KEY'],
    prompt='You are a helpful and friendly AI assistant.',
    voice=VoiceStyle.F1,
    language=Language.ENGLISH,
    on_transcription=on_transcription,
    on_response=on_response,
)

client.start_conversation()

start_conversation() uses the local microphone and speakers: install pip install "lokutor[audio]".client.on(event, callback) also works if you’d rather register handlers after construction — but note it takes the callback as an argument (client.on('transcription', on_transcription)), it is not a @client.on(...) decorator.

Running a dashboard agent

Pass agentId to run an agent you built in the dashboard, with its prompt, voice, language, tools, knowledge base and integrations. prompt, voice and language are then optional, and the SDK sends them only if you set them, as overrides for this session.

const client = new VoiceAgentClient({ auth: getTicket, agentId: '34da7ae3-0d46-4827-8739-ca6a25dc756c' });
await client.startManaged();

For an agentId that is not on your account the server refuses the handshake with 404 agent.not_found; a browser sees only a failed connection (ws.close).

Options

Option	Type	Default	Description
`auth`	`() => string \| Promise<string>`	—	Returns the credential, called before every connect and reconnect. Use it to fetch a `wst_` ticket from your backend.
`apiKey`	`string`	—	An API key (server-side) or a ticket. Optional when `auth` is given.
`agentId`	`string`	—	Run one of your dashboard agents
`prompt`	`string`	—	System prompt for the language model. Required unless `agentId` is set.
`voice`	`VoiceStyle`	`F1`	Voice slot (Voices). With `agentId`, the agent’s own unless you set it.
`language`	`Language`, `'auto'` or `''`	`ENGLISH`	Language. With `agentId`, the agent’s own unless you set it. `'auto'` (or `''`, JS 1.9.0) lets the agent follow the caller’s language.
`visemes`	`boolean`	`false`	Lip-sync data. Not available on the current model (Visemes).
`onTranscription`, `onResponse`, `onStatus`, `onError`	functions	—	Constructor callbacks. Each fires once per event, alongside any `on(...)` listeners for the same event.
`tools`	`ToolDefinition[]`	`[]`	Tool definitions for function calling
`serverUrl`	`string`	`wss://api.lokutor.com/ws/agent`	Custom endpoint

Events

Event	Payload	When
`transcription`	`string`	A final line of user speech
`transcription_partial`	`string`	Interim user text while they are still speaking. Not stored in the transcript
`response`	`string`	Agent text response
`audio`	`Uint8Array`	Audio chunk received
`visemes`	`Viseme[]`	Lip-sync data. Not sent on the current model
`status`	`string`	`listening`, `thinking`, `speaking`, `interrupted`, plus the client-only `reconnecting`/`disconnected` values emitted while the WebSocket itself is down or after the server ended the session (never sent by the server — see WebSocket Protocol)
`error`	`LokutorError`	Error occurred
`tool_call`	`{ name, arguments, call_id }`	The model called one of your tools. Fires once per call; pass `call_id` to `submitToolResult` (Tool Calling)
`reconnected`	—	Fired (separately from `status`) after a dropped connection successfully reconnects
`ended`	`{ code, reason }`	The server ended the session on purpose (the agent ended the call, or a limit was reached). No reconnection follows; `error` fires with code `session.ended` and the server’s reason
`session_limit`	`{ seconds, reason }`	The server announced how long this session may still run. Only sessions with a limit receive it (today: the key-less demo on lokutor.com); API-key sessions do not

Methods

// Start the conversation (browser) — the recommended entry point
await client.startManaged();

// Or connect manually (e.g. to pass a custom AudioManager)
await client.connect();

// Update session config mid-conversation
client.updatePrompt('You are now a pirate.');
client.updateVoice(VoiceStyle.M2);
client.updateLanguage(Language.SPANISH);
client.updateTools(newToolDefinitions);

// Get conversation history (final lines only; partial transcripts are not stored)
const history = client.getTranscript();       // [{ role, text, timestamp }]
const text = client.getTranscriptText();      // formatted string

// Mute / volume
client.toggleMute();
const amp = client.getAmplitude();            // 0–1

// Submit a tool result (call_id from the tool_call event)
client.submitToolResult(call_id, result);

// End the session
client.disconnect();

Also available: the connected and generation read-only properties, and onAudio(cb) / onVisemes(cb) as shorthand for on('audio', cb) / on('visemes', cb). Full signatures are in the JavaScript API Reference.

Status flow

listening → thinking → speaking → listening
                ↑
          interrupted

Reconnection

The client reconnects only when the connection drops or the server goes away (WebSocket close codes 1001, 1006, 1011–1014): exponential backoff 2s → 4s → 8s → cap at 10s, max 5 attempts, status reconnecting meanwhile. Each reconnection is a new server session — the conversation starts over — and reuses the running microphone. When the server closes the session on purpose — 1000 when the agent ends the call, 1008 when a limit is reached, 4xxx for other application reasons — the client does not reconnect. It fires error with a LokutorError of code session.ended whose message is the server’s reason, then status disconnected and the ended event. (Before 1.5.0 it reconnected into a fresh session instead.)

Starting a call on a phone

Ask for the microphone inside the tap that starts the call, with requestMicrophone(), and pass the result to BrowserAudioManager as microphone (see the JavaScript reference). Asked for later — after the connection opens — iOS Safari can refuse it without showing its prompt, and in the audio session’s 'playback' mode it always does. If the microphone cannot start, connect() rejects with code audio.microphone_unavailable and the session is closed rather than left talking to nobody.

Keeping the screen on

In the browser, BrowserAudioManager keeps the screen awake while the microphone is live (Screen Wake Lock), the way a video player does: a phone that dims and locks mid-call suspends the page’s microphone and audio. The lock is taken again when the page returns to the foreground and released when the call ends. Pass keepAwake: false to manage this yourself.

Get Started

SDK

API Reference

Resources

Basic usage

Running a dashboard agent

Options

Events

Methods

Status flow

Reconnection

Starting a call on a phone

Keeping the screen on

​Basic usage

​Running a dashboard agent

​Options

​Events

​Methods

​Status flow

​Reconnection

​Starting a call on a phone

​Keeping the screen on

Basic usage

Running a dashboard agent

Options

Events

Methods

Status flow

Reconnection

Starting a call on a phone

Keeping the screen on