Chat SDK

The Chat SDK is a small, self-contained client that turns a user's prompt into a live agent conversation and streams the reply back as it is produced. You embed it in your own web app; it opens a secure WebSocket to KeenAgents, runs an agent, and hands you the answer token by token through a callback. You work with a single class — ChatAPI: you construct it, register a few callbacks, connect, and call runFlow for each turn.

The connection carries no credentials in its URL — the consumer's short-lived session token rides inside the run, and the platform re-verifies it on every turn. Everything on the connection is tenant-scoped: a client opened for one tenant can only ever reach that tenant's agents and data.

You create one client per open conversation, passing the space it targets, the agent to run, and the signed-in consumer's identity and session token. Build it once (not on every render) and keep the instance around — the socket only opens when you call connect().

import { ChatAPI } from '@your-org/keen-chat-sdk';

const chat = new ChatAPI({
  spaceID,        // the space the run targets (also the project id)
  agentID,        // the agent SLUG — not the admin row id
  userId,         // the signed-in consumer's id
  email,          // the signed-in consumer's email
  accessToken,    // the consumer's short-lived session token
  url             // the platform chat endpoint (wss:// in production)
});

spaceID

The space the conversation runs in. It doubles as the project id, so projectID is optional and defaults to this value.

agentID

The agent's slug — the human-readable id, never the admin row id. Passing the row id comes back as agent-not-found. Resolve the slug from your agent record before constructing the client.

userId & email

The signed-in consumer's id and email. They identify who the conversation belongs to and are checked against the session token on every turn.

accessToken

The consumer's short-lived session token, from the two-token model. It is verified on every turn, so it can be refreshed on a live client without reconnecting — see Keeping the Session Token Fresh.

url

The platform's chat endpoint. Use a secure wss:// URL in production; a plain ws:// URL only for local http development. Point it at the platform — not at your own dev server — or the connection closes on its own.

cookies (optional)

Request-scoped cookies to forward to your flow's script nodes on the first turn — a list of names, or an explicit { name: value } map. Covered under Passing Cookies to Your Flow.

contextBatchSize (optional)

How many parallel copies a fan-out flow drains per wave (a positive integer; defaults to a sensible value). Raising it past what the platform admits at once just meets backpressure, not more throughput, so most apps leave it unset.

Register your callbacks before connecting so no early frame is missed, then open the socket. Each user message is one call to runFlow, keyed by a chatId that groups the turns of one conversation.

// 1) Wire callbacks BEFORE connect() — see "The Callbacks You Wire".
chat.onStatus(status => setStatus(status));      // 'disconnected' | 'connecting' | 'connected'
chat.onRunning(running => setRunning(running));  // true while a turn is in flight
chat.onStream((event, data) => {
  if (event === 'token') appendToReply(data.text);   // the live answer
  else                   showStatusRow(event, data);  // thinking / processing / error
});

// 2) Open the connection.
chat.connect();

// 3) Send a turn. chatId is required; it groups this conversation's turns.
await chat.runFlow({ chatId, prompt });

The awaited value is not the answer. runFlow resolves to a snapshot of the run for inspection; the text a user reads arrives through onStream as token events that you accumulate into one reply. This is the single most important thing to internalize about the SDK.

Only one turn runs at a time — a second runFlow while one is in flight is rejected, which is why you gate your Send control on the running state. A turn can be stopped with cancel():

async function send(prompt) {
  try {
    await chat.runFlow({ chatId, prompt });
  } catch (err) {
    // A canceled turn settles as a cancellation, not an error — show a quiet
    // "Canceled." row; anything else is a real failure row.
  }
}

// Stop a response in progress; the conversation stays open for the next turn.
chat.cancel();

onStream

The agent's live output — this is where the answer arrives. Each call carries an event and its data: token events accumulate into one reply bubble, while thinking, processing and progress render as status rows so a long, multi-step run reads as progress rather than a frozen screen, and error renders as an error row.

onStatus

The connection lifecycle — disconnected, connecting, connected. Drive your connection indicator off it and gate Send on connected.

onRunning

A boolean that flips true the instant a turn starts and false when it settles — success, cancel, or failure. This is the canonical Send/Cancel gate; pair it with onStatus.

onSystem

Transport diagnostics only — socket opened, socket closed, connection errors. Wire it to a log for debugging connectivity; never render it as the agent's answer. A connection that closes on its own surfaces here, not on onStream.

The split worth memorizing is onStream for application output versus onSystem for transport diagnostics. Two further callbacks exist for advanced cases — one that fires once when the connection is fully established, and one that carries every reply for a log or stats panel — but most apps never need them.

Here is exactly what each callback hands you and in what shape, with an example.

// onStream(event, data, requestId?)
//   event: 'thinking' | 'processing' | 'progress' | 'token' | 'error'
//   data:  the frame body for that event (envelope already stripped)
chat.onStream((event, data) => {
  if (event === 'token') {
    // data = { text: 'Hello', requestId: 'r-8f2a…' }  — the next slice of the answer
    appendToReply(data.text);
  } else if (event === 'error') {
    // data = { text: 'Script node failed: timeout' }  — a run-level failure to render as an error row
    showErrorRow(data.text);
  } else {
    // 'thinking' | 'processing' | 'progress'  — data.text is a human-readable status line
    showStatusRow(event, data.text);
  }
});

// onStatus(status)  — status is one string
//   'disconnected' | 'connecting' | 'connected' | 'unauthorized'
chat.onStatus((status) => setConnected(status === 'connected'));

// onRunning(running)  — a boolean: true the instant a turn starts, false when it settles
chat.onRunning((running) => setSendDisabled(running));

// onSystem(text)  — text is a plain string describing a transport event
chat.onSystem((text) => {
  // examples of what actually arrives here:
  //   'open wss://…'          the socket opened
  //   'close (code 1006)'     dropped — Origin not allow-listed, wrong URL, or network blip
  //   'close (code 1009 …)'   a frame exceeded the 8 MB cap
  //   'socket error'          a low-level connection error
  console.debug('[transport]', text);
});

// onWelcome(payload)  — fires once, right after the connection is established
chat.onWelcome((payload) => {
  // payload = { correlationID: 'c-4a1b…' }  — the id the platform tags this connection with
  console.debug('connected as', payload.correlationID);
});

// onResponse(envelope, requestId)  — every completed reply; for a log/stats panel, not the chat bubble
chat.onResponse((envelope, requestId) => {
  // envelope = { success: true, code: '…', message: 'OK', data: { … } }
  //   success — did the turn complete;  message — a short human-readable note
  logPanel.push({ requestId, ok: envelope.success, note: envelope.message });
});

A conversation can stay open longer than a single session token lives, and the platform verifies the token on every turn. So a long-lived chat would eventually start refusing sends. The client is built for this: the access token is mutable through setAccessToken(), so a refreshed token lands on the next turn without dropping the socket.

// Push a freshly minted token onto the live client — no reconnect.
chat.setAccessToken(freshAccessToken);

A practical pattern is to refresh on an interval while the chat is open and hand the new token to setAccessToken(). If the token has already expired mid-conversation the socket stays open and the send is refused — refresh and retry on the same connection. Only when the session is genuinely over (no new token can be minted) do you sign the user out; leave the client alone until then.

A flow's script nodes can read request-scoped cookies the consumer carried in — for example a connect token dropped by an OAuth consent. You choose what to forward with the constructor's cookies option, in one of two shapes. Cookies ride the first turn only; the platform scopes them to that run, and a script node reads a value back by name.

// Shape 1 — a list of NAMES: forward only these JS-readable browser cookies.
new ChatAPI({ /* … */, cookies: ['gconnect', 'locale'] });

// Shape 2 — an explicit map: supply the values directly, no browser needed.
new ChatAPI({ /* … */, cookies: { gconnect: '<token>' } });

• Omit the option to forward every JS-readable browser cookie; pass [] to forward none. Naming the cookies you actually need keeps unrelated ones from riding along.
• Cookies marked HttpOnly are never visible to the browser path, so they can't be forwarded by name. Use the explicit map only for values you already hold.
• Forwarded values are run-scoped and short-lived — they belong to that one turn and are cleared when it ends. Script nodes read them; they can never set a cookie back on the browser.

A single runFlow call hands the turn to the client's internal run queue, which drives the whole exchange for you: it sends the opening frame, works through the flow's nodes as the platform reports them, streams tokens to onStream as they arrive, and settles when the run reaches its end. You await one call; the queue does all the step-by-step bookkeeping. On every step it reads a status and decides what to do — and that decision is the behavior worth understanding.

Busy / no capacityretried

When the platform is briefly out of room, a step comes back as try again. The queue holds and retries the same step, with backoff, patiently — it does not raise an error or drop the turn. Your turn is never lost to a busy moment; you just see a slower first token. This is the guaranteed-execution model.

Terminal failurestops

A failure retrying can't fix — an unknown agent, a rejected token, a flow-level error — stops the turn immediately. The queue does not loop on it: it settles the run, flips onRunning to false, and delivers the reason (agent errors on onStream, transport on onSystem). See the catalog below for each case.

Oversized turnrefused up front

A turn over the 8 MB cap is refused before it is sent — the queue never enters the retry path for it, so there is no loop to escape. This is the one failure that surfaces synchronously at the send rather than through a callback.

Cancelclean teardown

A cancel signals the queue to stop. It tears down the run cleanly, keeps any partial output already streamed, and settles the turn as Canceled — no error, no dangling work.

Fan-out / parallelbatched

When a flow fans out — a step that spawns many sub-runs at once — the queue drains them in batches rather than all together, so a wide fan-out doesn't flood the socket. The batch size defaults to a safe value and is tunable through the constructor's contextBatchSize.

Failures reach your app through the callbacks you already wire — never as a thrown exception you have to catch around a send. The rule of thumb: an agent- or flow-level failure lands on onStream as an error event you render as an error row, while a transport failure lands on onSystem. In both cases onRunning flips back to false, so your Send button re-enables on its own. Each failure below is tagged with how the system treats it.

Message too largeyou fix it

A single turn is capped at 8 MB. An oversized turn is refused up front and not retried — the client stops it before it ever leaves, so you get an immediate, terminal failure instead of an endless retry loop. On the transport this is a WebSocket close 1009 (message too big). Fix: keep large data out of the prompt and pass a reference your flow resolves.

Session token expiredrefresh & retry

The platform verifies the token on every turn, so a long-lived chat eventually sends with a stale one. The send is refused but the socket stays open. Fix: mint a fresh token, hand it to setAccessToken(), and retry on the same connection — no reconnect. Sign the user out only when no new token can be minted.

Unknown agent or spaceyou fix it

The run is rejected as not found — almost always because a row id was passed where the agent slug belongs, or the agent isn't enabled in that space. Fix: run by the agent's slug and confirm it's deployed and active in the space. Terminal until the identity is corrected.

Agent / flow errorsurfaced, not fatal

A failure inside the run — a script node that threw, a model that errored — arrives on onStream as an error event carrying a human-readable reason. Render it as an error row. The conversation and socket stay usable for the next turn; nothing is torn down.

You cancelled the turnclean

Not an error. A cancel unwinds the run cleanly: any partial output already streamed is kept, the row settles as Canceled, and onRunning flips to false. Send the next turn whenever you like.

Connection droppedcheck setup

A socket that closes on its own surfaces on onSystem (never as the agent's answer). The one you'll actually see is close 1006 (abnormal): usually the page's Origin isn't allow-listed, the WebSocket URL is wrong, or the network blinked. Fix: confirm the URL points at the platform and the calling Origin is registered for your API key, then reconnect.

Busy under loadauto-handled

When capacity is tight the platform doesn't drop your turn — the client retries on its own until a slot frees. You see this as a slightly slower first token, never a lost answer. Nothing to handle; it's the guaranteed-execution model doing its job.

• A single message is capped at 8 MB. An oversized turn is rejected up front with a non-retryable error rather than retried forever — keep large payloads out of the prompt and pass a reference your flow can resolve instead.
• The answer arrives on onStream, not from the runFlow return value. Wire the stream first; the awaited value is for inspecting the run.
• Register callbacks before connect(), construct the client once (not per render), and disconnect() when the view unmounts — that keeps sockets from leaking across navigations.
• Under heavy load a busy moment shows up as a slightly slower first token, never a dropped answer. The client also keeps a live run warm on its own during idle gaps, so a slow model doesn't age out the conversation.