Core concepts
The vocabulary used across these docs — host, capability, adapter, conversations and members, messages, runs, interactive cards, the message store, frames and signals — and how they fit together.
Core concepts
This page is the glossary for the whole site. Wherever another page uses these words, they mean what is written here.
import {
ChatProvider,
ChatRoot,
ChatSplitLayout,
ConversationHeader,
CwsConversationList,
CwsMessageThread,
createChatHost,
} from "@openmaxai/chat-sdk/react";
import { createMemoryAdapter } from "@openmaxai/chat-sdk/testing";
// The host: everything the components need comes from here; the adapter connects it to a backend, here an in-browser memory backend
const host = createChatHost({ adapter: createMemoryAdapter() });
<ChatProvider host={host}>
<ChatRoot style={{ display: "flex", height: "100%" }}>
<ChatSplitLayout
open={selected !== null}
list={<CwsConversationList selectedId={selectedId} onSelect={(c) => setSelectedId(c.id)} />}
>
{selected && (
<>
<ConversationHeader conversation={selected} onBack={() => setSelectedId(null)} />
<CwsMessageThread conversation={selected} />
</>
)}
</ChatSplitLayout>
</ChatRoot>
</ChatProvider>;
The styles come from @openmaxai/chat-sdk/styles.css and apply only inside the component root each SDK component (Cws*) brings along, so the components go inside ChatRoot. For the complete, runnable version see Quick start.
Host
The host (ChatHost) is the object that connects the chat components to your backend. The components
never send requests, touch the router or use browser storage themselves; they go through the host.
Install it once with <ChatProvider>, whether createChatHost made it or you wrote it yourself.
| How to get a host | Use it for |
|---|---|
createChatHost(config) from @openmaxai/chat-sdk/react |
An OpenMax backend |
Write identity, messaging and inboundDelivery yourself, fill the rest with createLocalPorts() |
Any other backend, mocks, tests |
A host you write yourself only works with the components of @openmaxai/chat (ConversationList, MessageThread and the rest): SDK components such as CwsConversationList and CwsMessageThread read internals that only a createChatHost host has, and throw on render under a hand-written host. The components of @openmaxai/chat have no style root, so the stylesheet does not reach them: put them inside ChatRoot and wrap them in an element with the class omx-chat (plus omx-dark in dark mode, with colorScheme="dark" on ChatRoot), or style them yourself. A wrapper alone is not enough: outside ChatRoot, dialogs, menus and popovers portal to document.body, outside your wrapper, and get no styles; within ChatRoot they land in its overlay container, which carries the class omx-chat. See Connect your own backend.
Required parts of a host: identity, messaging, inboundDelivery, drafts, render, attention,
i18n, instanceScope, attachments. createLocalPorts() provides the last six.
Capabilities
A capability is one field on the host, such as messaging, cards, mentions or profileCard. Required
capabilities are needed by every component, so the host must provide them. Optional capabilities may be left
out, and what happens then is one of two things:
- Most components and composer plugins: only the UI that uses the capability is hidden; everything else
works. For example, without
profileCardavatars are not clickable, but chat works as usual. Composer plugins work the same way: a plugin whose capability is missing is not installed, so withoutworkItemsthe composer has no#. - Conversation list and group management: they throw. Each of these components is built entirely on its
capability (
conversationsandgroupManagementrespectively) and has nothing to fall back to. Both capabilities are optional for the SDK as a whole, but required if you use the matching component.
Type names keep the Port suffix (for example ChatCardsPort); each one is a capability. The full list,
and what happens when one is missing, is in Capabilities.
Adapter
An adapter is the backend-specific implementation: it keeps the connection, turns server frames into
events and provides the read calls; the SDK wraps it into a host. The OpenMax adapter is
createOpenMaxAdapter in the @openmaxai/chat-openmax package; another backend writes its own adapter and passes it to
createChatHost({ adapter }). See
Architecture overview; the interface is in Adapter interface.
Conversations
A conversation (ChatConversation) is a direct message (DM) or a group (GROUP). CwsConversationList
shows a list of them and CwsMessageThread shows one conversation's messages; both take conversation objects.
Members
A member (ChatParticipant) is one party in a conversation, with kind set to human or agent. An
agent receives messages, sends messages and can be @-mentioned like a person, and stays in the
conversation. Every agent belongs to one person, its owner; the owner can switch its model in their direct
message with it.
There are also observers: people who are not members but can read the conversation, for example an agent's owner looking at the agent's direct message with someone else. Observers see the same live content as members.
Messages
A message (ChatMessage) is one entry in a conversation: text, an image, a file, a card, a system notice
or an agent's reply. Every message has an integer seq that starts at 1 and increases within the
conversation without repeats. Ordering and catching up after a disconnect both depend on it.
Runs
Planned
A run is everything an agent does to handle one input: queued, started, calling tools, finished or
failed. A run has a run_id minted by the backend, belongs to at most one conversation, and everyone in
that conversation sees its progress. Work an agent hands to a subagent stays in the same run and is shown grouped
by subagent invocation. The agent's final reply is still an ordinary message, carrying the id of the run it belongs to.
Run progress events take AG-UI 1.0 as the reference: events that fit keep AG-UI's names and fields, and
where we need something different we extend it and mark each place. They are pushed as agent_event frames
on the realtime connection and do not take a conversation seq. The host stops runs (or just one subagent
invocation) and fetches run snapshots through the agentRuns capability. See Connect your own backend · Agent runs.
Interactive cards
A card is a message with structured content (cws.card.v1), rendered automatically by CwsMessageThread.
A card with buttons or options that people answer directly is an interactive card. The card body
always shows; answering needs the cards capability.
Planned: an interactive card can be bound to a run. A card carrying run_id, tool_call_id and expires_at is an approval card: the agent waits for an answer, and the answer goes back to the agent as the result of that tool call. Planned See Interactive cards.
Message store
The message store is the client-side data store in the shared layer, one per host: createChatHost
creates it, and CwsMessageThread reads from and writes through it. Every write goes through one entry
point; local storage plugs in through the ChatStorage interface. Putting Agent runs in the store is still planned. See
@openmaxai/chat-store and @openmaxai/chat-sdk · Message store.
Frames and signals
- A frame is one piece of data the server pushes over the realtime connection. Frames report new messages, reactions, read positions, card updates and similar changes, and the
agent_eventframe carries run events. Planned - A signal (
ChatInboundSignal) is the notification the host passes to the components after translating a frame, such as{ kind: "messages", conversationId }or{ kind: "reconnected" }.
Missed messages are fetched from the seq watermark onward (gap-fill); missed run events are recovered
from a run snapshot. See Realtime and sync.
How it fits together
| Layer | What it is | More |
|---|---|---|
| Components | Only draw the UI; get everything from the host | Components |
| Host and capabilities | The contract between the components and your app | Capabilities |
| Message store | Where messages, runs and request results live on the client | @openmaxai/chat-store |
| Frames and signals | How server changes reach the client, and how gaps are filled | Realtime and sync |
| Backend | Your API, or OpenMax | Connect your own backend |
