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.

An MCP consumer — the headless identity an AI agent creates through the Keen MCP server — uses this surface too: its token rides the connection the same way, its user id is the consumer's ID, and every message is checked against the same space and tenant rules. Only the way the token is obtained differs (see MCP Consumers).

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 — the chat error code your client receives — 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 the chat error code E3101 on every outstanding token for that tenant; re-login is the recovery.
• A run against a space the consumer is not granted, or a space the tenant no longer offers, is refused with a space-authorization error; a run for a missing or inactive 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, renaming and deleting past conversations is done over the HTTPS chat routes, covered on the Self-Service page — live chat produces the history those routes read.