Live Chat

Live chat is the real-time surface where a consumer talks to your agents. A partner's browser application opens a secure WebSocket connection to KeenAgents and runs an agent; the agent's reply streams back token by token as it is produced, so your UI can render the answer as it forms instead of waiting for a finished block. It is a live connection: a single socket carries the whole conversation, message after message.

The chat connection is authenticated the same way every consumer call is — with the consumer's short-lived access_token, from an origin your organization has allow-listed. Everything on the connection is tenant-scoped: a socket opened for one tenant can only ever reach that tenant's agents and data.

Connect

The browser opens the WebSocket carrying the consumer's access token. The connection is accepted only from an allow-listed origin; a request from an unknown origin is refused without explanation. Point the socket at the platform (not your own dev server) and use a secure wss:// connection.

Run an agent

To start a turn, send a message naming the agent (by its slug) and the space (the project ID), plus the user's prompt. KeenAgents authorizes the run — the token must grant the space, and the agent must exist and be active in it — then starts the agent's flow.

Stream the reply

The answer arrives as a stream of tokens on the same socket while the agent is still generating it, so the UI can show the reply as it forms. The completed exchange is saved to the conversation's history.

Cancel

A response in progress can be canceled. The platform stops the run and drops its in-flight work; the conversation stays open and ready for the next message.

A live socket can outlast logins, policy changes and credential rotations, so KeenAgents re-verifies the access token on every message, not once at connect. On each message the requested space must be both in the consumer's own grant and currently allowed by the tenant's contract — revoke a space and it stops working immediately — and the tenant is resolved from the verified credentials, overwriting anything the client sends. A client can never choose its own tenant partition.

• An access token that expires mid-conversation surfaces as E3002 but leaves the socket open — refresh the token and retry on the same connection. The connection outlives the token by design.
• A rotated tenant key surfaces as E3101 on every outstanding token for that tenant; re-login is the recovery.
• A run against the wrong space, or for an inactive or missing agent, is refused as agent-not-found — authorization requires both space access and the agent actually living in that space.

• Run an agent by its slug, never by the admin row id — the row id is refused as agent-not-found. Renaming an agent's slug immediately changes what a run resolves to, so update your chat client if a slug changes.
• The WebSocket URL must point at the platform, and its origin must match the origin your consumer token was minted for. Pointing the socket at your local dev server, or serving the page from a second origin, shows up as a connection that closes on its own.
• Many conversations run at once and stay responsive under load; a busy moment shows up as a slightly slower first token, not a dropped answer.
• Listing, searching, reading and archiving past conversations is done over the HTTPS chat routes, covered on the Self-Service page — live chat produces the history those routes read.