OpenMax
Free Trial

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 profileCard avatars are not clickable, but chat works as usual. Composer plugins work the same way: a plugin whose capability is missing is not installed, so without workItems the composer has no #.
  • Conversation list and group management: they throw. Each of these components is built entirely on its capability (conversations and groupManagement respectively) 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_event frame 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