OpenMax
Free Trial

Connect your own backend

Write a ChatHost for your own API — the three backend-facing required capabilities and the conversation list by hand, the rest from createLocalPorts — then wire up agent run events and endpoints.

Connect your own backend

The components read everything from one host (ChatHost object). You write the server-facing capabilities: the required identity, messaging and inboundDelivery, plus conversations for the conversation list (optional, but ConversationList throws without it). createLocalPorts from @openmaxai/chat-sdk/react fills in the other six required ones (drafts, attachments, render, attention, i18n, instance scope), nine required in all; see Capabilities. Type the host as ChatHostWithConversationList and a missing conversations fails to compile. When conversations have agents, also wire up run events as described in Agent runs. A checklist closes the page.

Capability What it does
identity Current user, member lookup, directory search
messaging Send a message, load thread pages, create a conversation
inboundDelivery Parameters of the realtime connection the SDK opens; a demo host pushes signals through subscribe
conversations The conversation list: list, pin, hide (optional; required when you render ConversationList)

A complete host

A trimmed in-memory host. Replace the arrays with calls to your API.

src/my-host.ts

import type {
  ChatHostWithConversationList,
  ChatInboundSignal,
  ChatMessage,
  ChatParticipant,
} from "@openmaxai/chat/host";
import { createLocalPorts } from "@openmaxai/chat-sdk/react";

const ME = "me";
const people: ChatParticipant[] = [
  { memberId: ME, displayName: "You", kind: "human" },
  { memberId: "ada", displayName: "Ada", kind: "human" },
];

const subscribers = new Set<(signal: ChatInboundSignal) => void>();

export function createMyHost(api: MyApi): ChatHostWithConversationList {
  return {
    identity: {
      currentUserId: () => ME,
      getMember: (id) => people.find((p) => p.memberId === id),
      listMembers: () => people,
      searchDirectory: async ({ search }) => ({
        members: people
          .filter((p) => p.displayName.toLowerCase().includes(search.toLowerCase()))
          .map((p) => ({ ...p, isActive: true })),
      }),
    },

    messaging: {
      sendMessage: async (input) => {
        await api.send(input);
      },
      loadThread: async (conversationId, cursor) => {
        const page = await api.messages(conversationId, { before: cursor });
        return { messages: page.items, nextCursor: page.prev ?? undefined };
      },
      loadThreadSince: async (conversationId, afterSeq) =>
        (await api.messages(conversationId, { afterSeq })).items,
      createConversation: async ({ memberIds, title }) => ({
        conversationId: (await api.createRoom(memberIds, title)).id,
      }),
    },

    inboundDelivery: {
      endpointUrl: () => "",
      authToken: async () => undefined,
      clientId: () => "my-app",
      isMock: () => true, // you deliver signals yourself through `subscribe`
      subscribe: (onSignal) => {
        subscribers.add(onSignal);
        return () => void subscribers.delete(onSignal);
      },
    },

    conversations: {
      list: async ({ cursor }) => {
        const page = await api.rooms({ after: cursor });
        return { conversations: page.items, nextCursor: page.next ?? undefined };
      },
      setPinned: (id, pinned) => api.pin(id, pinned),
      setHidden: (id, hidden) => api.hide(id, hidden),
    },

    ...createLocalPorts({
      scope: "my-chat",
      currentUserId: () => ME,
      locale: "en-US",
    }),
  };
}

// When your server pushes "conversation X has new messages":
export function onServerPush(conversationId: string) {
  for (const notify of subscribers) notify({ kind: "messages", conversationId });
}

Install it with <ChatProvider host={host}>, the same as a host made by createChatHost; see Installation. Composer plugins whose capabilities the host lacks are not installed: without workItems there is no #; see Capabilities.

A hand-written host only works with the components of @openmaxai/chat (ConversationList, MessageThread and the rest): SDK components such as CwsConversationList, CwsMessageThread and ConversationHeader 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: @openmaxai/chat-sdk/styles.css applies only inside the .omx-chat component root each SDK component brings along, and ChatRoot is not a style scope itself, so they render unstyled. 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. To use the styled SDK components as they are, write an adapter instead and pass it to createChatHost; see Adapter API.

Rules that are easy to get wrong

Messages. ChatMessage and ChatConversation are defined by the SDK with the same field names as OpenMax; map your records into them. Fields: Data model. Every message needs a seq, an integer unique and increasing within a conversation. Ordering and gap-fill depend on it. Missing fields usually do not throw; the UI just shows less. See Known limitations.

Identity is synchronous. currentUserId(), getMember() and listMembers() return values, not promises. Load the data before rendering, or cache it and give ChatProvider a new host object (with a new identity) when it arrives. Until then your own messages are drawn as someone else's.

Paging. loadThread pages backwards along an opaque cursor. Return nextCursor whenever the server has more, even on a short page. loadThreadSince(id, seq) returns only messages with a higher seq, or [].

Realtime signals. subscribe delivers signals such as { kind: "messages", conversationId }; the thread then calls loadThreadSince. Other kinds are reconnected, reaction, messageChanged (someone edited or recalled a message, or moderation removed it; the thread fetches the edited text with loadMessage), read, delivery and card; their fields are on Realtime and sync. Emit { kind: "reconnected" } after every reconnect to tell the UI the connection is back. The realtime connection belongs to the SDK: when isMock() is false, the SDK connects itself using endpointUrl(), authToken() and clientId(). The in-memory host above is a demo, so isMock() returns true and it pushes signals itself. If your app still keeps its own connection while migrating, forward that connection's signals through subscribe and the SDK does not open another; once your own connection is gone, drop subscribe too.

Blocked sends. If your content filter drops a message, return { blocked: { refusalText } } from sendMessage instead of throwing. The thread keeps the message locally and shows your text.

Quoted excerpts and recall. Store and return a message's metadata unchanged and excerpt quotes (metadata.quote_excerpts) work. When a quoted message is recalled, the UI hides the excerpt only where it knows the quoted message is recalled; the excerpt text stays on the quoting message and anyone reading it from your API still sees it. To remove it, rewrite each item whose message_id is the recalled message to { message_id, recalled: true }, then send messageChanged with change: "edited" and the quoting message's messageId, without setting its edited_at (it was not edited).

Uploads

Pass an upload function to createLocalPorts. It moves the bytes and resolves to an attachment id; the SDK handles the task board, progress, cancel and limits.

...createLocalPorts({
  scope: "my-chat",
  currentUserId: () => ME,
  attachments: {
    limits: { maxAttachments: 5, maxFileSizeBytes: 50 * 1024 * 1024 },
    upload: async (file, { conversationId, signal, progress, finalizing }) => {
      const { id } = await api.upload(file, { conversationId, signal, onProgress: progress });
      return id;
    },
    resolveUrls: async (ids) => api.fileUrls(ids), // { [id]: url }; leave out ids you cannot resolve
  },
}),
  • Call progress(loaded, total) or the task stays at 0 %. Call finalizing() if the server processes the file after the bytes arrive.
  • Without attachments there is no attachment button; without resolveUrls received attachments show as unavailable.
  • conversationId is undefined: the UI does not say which conversation an upload is for. If your endpoint needs one, wrap each open thread inside ChatProvider in its own ChatHostProvider from @openmaxai/chat/host whose attachments closes over that conversation id, keeping the rest of the parent host (the OpenMax host's ConversationScope works this way). ChatHostProvider is not an install entry point; it only replaces capabilities for the part of the UI below it.

Other local capabilities

Pass ports to createLocalPorts to replace any of the six local capabilities:

import { createLocalPorts } from "@openmaxai/chat-sdk/react";

...createLocalPorts({
  scope: "my-chat",
  currentUserId: () => ME,
  ports: {
    attention: { notify: (level, text) => toast[level](text), setUnreadSignal: setBadge },
    render: myRender, // markdown, links, mentions
  },
}),

The default render draws agent replies as Markdown (see createMarkdownRender) and other text as plain text with line breaks, linked http(s) URLs and @mentions. The default attention does nothing, so error toasts are invisible until you replace it.

Optional capabilities

Add optional fields to the host (such as mentions, profileCard, cards, groupManagement, and the reaction, recall and edit methods on messaging) to switch on more features. On success the reaction, recall and edit methods may return { changeSeq } (when your backend numbers the change), or void otherwise; when the server explicitly refuses, throw a ChatSdkError with kind forbidden (new ChatSdkError("forbidden", message), imported from @openmaxai/chat-sdk), so recall and edit say "cannot recall / cannot edit". What each one does and what happens without it: Capabilities. Signatures and error rules for every member: Host capabilities.

Agent runs

Planned

To show agent run progress, tool steps and a stop button in conversations, the SDK needs two things: agent events received in realtime, and methods on the host's agentRuns capability (stop, the conversation's run snapshot, fetching one run's events by run_id, and the agent's run snapshot for the Agent panel). How the frames and endpoints look on the wire is up to you; below are reference shapes, which the OpenMax backend will use as well. The rules themselves are on Realtime and sync.

What the backend does

  1. Generate run_id on dispatch. When dispatching the triggering message to the agent, generate a run_id, record its conversation and agent, hand it to the agent with the message, and push a queued frame (run_seq 0, queued: true).
  2. Route by run_id only. For each reported event, find the conversation bound to its run_id. Reject events with no run_id, an unknown run_id or one that does not belong to this agent, or a threadId that differs from the binding. Before any work other than a dispatched message, the agent calls Create a run; work handed to a subagent needs no new run, it stays in the current run and carries subagentRunId.
  3. Push agent_event frames on the chat's own WebSocket; the format is on Realtime and sync:
    • Recipients are the same as for messages: members and observers of the conversation the run_id is bound to, and no other conversation. All of the agent's runs (including unbound ones) also go to people viewing its Agent panel whom your application allows.
    • Fill permissions per recipient: cancel: true for the run's initiator and the agent's owner (only the owner for a run with no initiator; your application may add people by its own rules).
    • Push TOOL_CALL_ARGS and TOOL_CALL_RESULT to recipients according to the agent owner's setting; when the owner is observing, push them to the owner.
    • Push in run_seq order within a run. Pushing the same run_seq again is safe.
    • Forward event with no fields added or removed, so it stays a valid AG-UI 1.0 event; our own information goes in the envelope only.
    • End stalled runs: if the agent sends nothing for too long, push a RUN_ERROR on its behalf, so the UI does not stay on "Working". Our extension
    • Stopping: pass stop requests on to the agent. When only one subagent invocation is stopped, the agent closes it with SUBAGENT_ERROR whose code is "cancelled" and the run goes on Our extension; see Stop a run.
  4. Serve the reference endpoints: create a run, report events, stop, the two snapshots, and fetching a run's events; see Reference endpoints. Phase 2: the card-posting endpoint accepts run_id, tool_call_id and expires_at, and the answer goes back to the agent as that tool call's result.
  5. Put metadata.run_id on the final reply. The agent's final reply is sent as an ordinary message; the UI uses the run id to attach the run summary to it.

Phase 1 needs no SSE. A standard AG-UI SSE endpoint may be added later for external integrations, carrying the same events through a translation layer that handles our extensions to AG-UI 1.0.

Signals handed to the SDK

The host turns each agent_event frame into a ChatAgentEventSignal. The type of event is AG-UI 1.0's event union: @openmaxai/chat depends on @ag-ui/core 1.0.x and re-exports that type as AgUiEvent, so you do not install @ag-ui/core yourself:

import type { AgUiEvent } from "@openmaxai/chat/host";

interface ChatAgentEventSignal {
  kind: "agentEvent";
  /** Absent for runs not bound to a conversation (Agent panel only). */
  conversationId?: string;
  agentMemberId: string;
  runId: string;
  /** Sequence number within the run: 0 for the queued signal, then 1, 2, … per event. */
  runSeq: number;
  /** The run is queued; there is no event yet. */
  queued?: boolean;
  triggerMessageId?: string;
  /** What the current user may do with the run. */
  permissions?: { cancel?: boolean };
  /** The AG-UI 1.0 event, forwarded with no fields added or removed (a subagent's events carry subagentRunId). Absent on the queued signal. */
  event?: AgUiEvent;
}

A hand-written host pushes this signal from inboundDelivery.subscribe, through the same callback as the other signals, and puts agentRuns on the host:

import type { ChatHostWithConversationList } from "@openmaxai/chat/host";

export function createMyHost(api: MyApi): ChatHostWithConversationList {
  return {
    // identity, messaging, inboundDelivery, conversations… as above
    agentRuns: {
      cancelRun: ({ runId, subagentRunId }) => api.cancelRun(runId, subagentRunId),
      loadActiveRuns: async (conversationId) =>
        (await api.activeRuns(conversationId)).runs.flatMap(toAgentEventSignals),
      loadRunEvents: async ({ runId, afterRunSeq }) =>
        toAgentEventSignals(await api.runEvents(runId, afterRunSeq)),
    },
  };
}

// When the WebSocket receives an agent_event frame:
function onFrame(frame: Frame) {
  if (frame.type !== "agent_event") return;
  const p = frame.payload;
  for (const notify of subscribers)
    notify({
      kind: "agentEvent",
      conversationId: p.conversation_id,
      agentMemberId: p.agent_member_id,
      runId: p.run_id,
      runSeq: p.run_seq,
      queued: p.queued,
      triggerMessageId: p.trigger_message_id,
      permissions: p.permissions,
      event: p.event,
    });
}

agentRuns has the required methods cancelRun, loadActiveRuns and loadRunEvents, and the optional loadAgentRuns and describeTool. Deduping, ordering, filling gaps and deciding when to load a snapshot belong to the shared layer; the host only translates.

Reference endpoints

Our extension

The paths and fields below are a design draft, not in the code yet; names may change. These endpoints are ours and have no AG-UI 1.0 counterpart: AG-UI describes the event stream only, not how to create a run, report, stop or fetch missed events.

Create a run

Called by the agent before any work other than a dispatched message. Work handed to a subagent needs no new run: it stays in the current run. Pass one of:

  • A conversation (proactive work): the backend checks that the agent is a member of it, binds the run to it, and pushes the run's queued frame there.
  • No conversation (scheduled jobs, housekeeping and so on): the run is not bound to a conversation and appears only in the Agent panel. The response's thread_id is this agent's thread id, which the agent uses as threadId in the run's events.
POST /api/v1/agent-runs

With a conversation:

{ "conversation_id": "c_123" }
{ "run_id": "r_457", "conversation_id": "c_123" }

Without a conversation:

{}
{ "run_id": "r_458", "thread_id": "at_m_agent" }

Neither kind of run has an initiator, so only the agent's owner may stop it.

Agent reports events

The agent batches events and reports them in one request. The path has no conversation: each event's run_id decides it.

POST /api/v1/agent-events
{
  "events": [
    {
      "run_id": "r_456",
      "run_seq": 2,
      "event": { "type": "TOOL_CALL_START", "toolCallId": "t_1", "toolCallName": "web_search" }
    },
    {
      "run_id": "r_456",
      "run_seq": 3,
      "event": { "type": "TOOL_CALL_END", "toolCallId": "t_1" }
    }
  ]
}
  • Only run_ids the backend issued to this agent are accepted; one batch may contain runs from several conversations.
  • Within a run, events are in ascending run_seq; the backend dedupes by run_id + run_seq, so resending a whole batch is safe.
  • Success returns 202; each event is then pushed, by its run_id, to the people in that conversation.

Stop a run

POST /api/v1/agent-runs/{run_id}/cancel

An empty body stops the whole run; to stop only one subagent invocation, send its id Our extension:

{ "subagent_run_id": "sa_1" }
  • The path has no conversation: the backend generated the run_id and knows which conversation it is bound to, and runs not bound to a conversation use the same endpoint.
  • 202 on success: the backend has told the agent to stop. For the whole run, the agent first closes the subagent invocations still open, then the run ends with a RUN_FINISHED whose outcome is cancelled. With subagent_run_id, the agent closes that invocation and the ones it spawned with SUBAGENT_ERROR whose code is "cancelled", and the run goes on.
  • 403 without permission. 409 when the run, or the subagent invocation to stop, has already ended; the UI treats it as ended. 404 when the run has no such subagent invocation.
  • Stopping a run that is executing in the agent's main session may interrupt the main session too; see Message thread.
  • The run's initiator and the agent's owner may stop it, the whole run or any subagent invocation in it alike; a run with no initiator only the owner.

Run snapshot

GET /api/v1/conversations/{conversation_id}/runs/active
{
  "runs": [
    {
      "conversation_id": "c_123",
      "agent_member_id": "m_agent",
      "run_id": "r_456",
      "trigger_message_id": "msg_789",
      "protocol_version": "1.0",
      "permissions": { "cancel": false },
      "events": [
        { "run_seq": 1, "event": { "type": "RUN_STARTED", "threadId": "c_123", "runId": "r_456" } },
        { "run_seq": 2, "event": { "type": "TOOL_CALL_START", "toolCallId": "t_1", "toolCallName": "web_search" } }
      ]
    }
  ]
}

The conversation snapshot returns every unfinished run in the conversation (queued ones included, with empty events and "queued": true), each with all its events so far. Finished runs are not returned.

The Agent panel uses another snapshot with the same shape: every unfinished run of the agent, including unbound ones, callable by whoever your application allows:

GET /api/v1/agents/{agent_member_id}/runs/active

Fetch a run's events

Returns one run's envelope fields and events by run_id, whether or not the run has ended. The client calls it in three cases: a run_seq gap; a run the store still has as unfinished that is missing from a freshly loaded snapshot (most likely its ending frame was missed); and expanding a finished run. The rules are on Realtime and sync.

GET /api/v1/agent-runs/{run_id}/events?after_run_seq=2
{
  "conversation_id": "c_123",
  "agent_member_id": "m_agent",
  "run_id": "r_456",
  "trigger_message_id": "msg_789",
  "protocol_version": "1.0",
  "permissions": { "cancel": false },
  "events": [
    { "run_seq": 3, "event": { "type": "TOOL_CALL_END", "toolCallId": "t_1" } },
    { "run_seq": 4, "event": { "type": "RUN_FINISHED", "threadId": "c_123", "runId": "r_456" } }
  ]
}
  • after_run_seq is optional; without it, every event is returned.
  • 404 when the run does not exist or the current user may not see it; the client removes the run from the store.
  • Runs not bound to a conversation have no conversation_id; who may call this for them is your application's decision, by the same rules as the Agent panel.

Answer an approval card

Phase 2. Answers use the same request as the card's buttons; there is no new endpoint. When the card carries tool_call_id, the backend passes the answer to the agent as that tool call's result. Answering after expires_at returns an expiry error, which the host maps to window-expired. See Interactive cards.

Adapter API

The adapter API moves what a hand-written host must handle (synchronous identity cache, list invalidation, upload binding) into the SDK. You write a plain ChatSdkAdapter of async functions (identity.me(), members(), messaging, conversations, realtime.connect(sink), uploads.upload()) and pass it to createChatHost({ adapter }) from @openmaxai/chat-sdk. Capabilities follow presence: no realtime, no live updates; no uploads, no attachment button. Without a backend you can run the UI on the in-memory adapter from @openmaxai/chat-sdk/testing first, see Testing; the conformance suite does not exist yet.

Every member's signature, whether it is required and its error contract are in Adapter interface; on failure it throws ChatSdkError, with the kinds in Error model. An adapter with only the required members and realtime:

src/acme/adapter.ts

import { CHAT_SDK_ADAPTER_VERSION, type ChatSdkAdapter } from "@openmaxai/chat-sdk";
import { createChatHost } from "@openmaxai/chat-sdk/react";
import { type AcmeApi, api, redirectToLogin, toSignal } from "./acme-api";

export function createAcmeAdapter(api: AcmeApi): ChatSdkAdapter {
  return {
    adapterVersion: CHAT_SDK_ADAPTER_VERSION,
    name: "acme",
    identity: {
      me: () => api.me(),
      members: (conversationId) => api.members(conversationId),
      searchDirectory: (input) => api.searchPeople(input),
    },
    messaging: {
      sendMessage: (input) => api.send(input),
      loadThread: (conversationId, cursor) => api.messages(conversationId, { before: cursor }),
      loadThreadSince: (conversationId, afterSeq) => api.messagesAfter(conversationId, afterSeq),
      createConversation: (input) => api.createRoom(input),
    },
    realtime: {
      connect: (sink) => {
        const socket = api.openSocket({
          onFrame: (frame) => sink.signal(toSignal(frame)),
          onReconnected: () => sink.signal({ kind: "reconnected" }),
          onGiveUp: (error) => sink.error(error), // already a ChatSdkError
        });
        return { close: () => socket.close() };
      },
    },
  };
}

export const host = createChatHost({
  adapter: createAcmeAdapter(api),
  onUnauthorized: () => redirectToLogin(),
});

./acme-api stands for your own backend client: the AcmeApi interface, its instance api, toSignal (turns a socket frame into a signal such as { kind: "messages", conversationId }) and redirectToLogin.

Use this host the same way as in Quick start: the SDK components go inside ChatRoot, and your global CSS imports @openmaxai/chat-sdk/styles.css.

src/app.tsx

import {
  ChatProvider,
  ChatRoot,
  ChatSplitLayout,
  ConversationHeader,
  CwsConversationList,
  CwsMessageThread,
  useChatSdkConversationList,
} from "@openmaxai/chat-sdk/react";
import { useState } from "react";
import { host } from "./acme/adapter";

export function App() {
  return (
    <ChatProvider host={host}>
      <ChatRoot style={{ display: "flex", height: "100%" }}>
        <Chat />
      </ChatRoot>
    </ChatProvider>
  );
}

function Chat() {
  const { conversations } = useChatSdkConversationList();
  const [selectedId, setSelectedId] = useState<string | null>(null);
  const selected = conversations.find((c) => c.id === selectedId) ?? null;

  return (
    <ChatSplitLayout
      open={selected !== null}
      list={
        <CwsConversationList
          selectedId={selectedId}
          onSelect={(c) => setSelectedId(c.id)}
          onDeselect={() => setSelectedId(null)}
        />
      }
    >
      {selected && (
        <>
          <ConversationHeader
            conversation={selected}
            onBack={() => setSelectedId(null)}
          />
          <CwsMessageThread key={selected.id} conversation={selected} />
        </>
      )}
    </ChatSplitLayout>
  );
}

In the data layer an adapter does three things: it keeps the connection, turns server frames into events and emits reconnected after every reconnect; it provides two reads, loadThread (backwards along a cursor) and loadThreadSince (messages after a given seq); and it passes clientMessageId to the backend on send and returns it on messages read back. Caching, deduping, deciding when to fill gaps and device storage belong to the store package, part of the shared layer, so leave them out of the adapter. See @openmaxai/chat-store.

Agent events work the same way: hand ChatAgentEventSignal to sink in realtime.connect(sink) and put agentRuns on the adapter; the SDK wraps it as the host capability.Planned

The item marked planned (agent events) is not in the code yet. Planned

Checklist

Messages

  • Every message has an integer seq, starting at 1 and increasing without repeats within a conversation
  • currentUserId(), getMember() and listMembers() return synchronously; once identity data arrives, the host is replaced with a new object
  • loadThread pages backwards along a cursor and returns nextCursor whenever the server has more; loadThreadSince returns only messages with a higher seq, or []
  • subscribe delivers messages and the other signals, and reconnected after every reconnect
  • Messages dropped by the content filter return { blocked: { refusalText } } instead of throwing
  • Uploads call progress; URL resolution leaves out ids it cannot resolve
  • clientMessageId is passed to the backend on send as the deduplication key (resending the same key writes no second message) and returned unchanged as client_msg_id on messages read back
  • To support opening a conversation by id from a link, conversations.loadConversation is provided and returns undefined, without throwing, when the conversation does not exist or cannot be accessed Planned
  • If conversations.loadUnreadTotal is provided, it does not count muted conversations or conversations the user only observes Planned
  • render.renderMessageText draws the body of text messages as Markdown (messages from people are Markdown too), with mentions and links as usual Planned

Agent runs

Planned

Items marked "Our extension" are our own conventions beyond AG-UI 1.0. The rest are AG-UI 1.0's own rules or requirements of the SDK capability.

  • A run_id is generated and bound to the conversation on dispatch, and a queued frame is pushed Our extension
  • Routing uses run_id only; events without a run_id or whose threadId differs from the binding are rejected; runs not bound to a conversation go only to the Agent panel Our extension
  • agent_event frames go only to members and observers of the bound conversation, with permissions filled per person (cancel for the initiator and the owner, only the owner when there is no initiator) Our extension
  • threadId and runId in events match the envelope's conversation_id and run_id Our extension
  • The queued frame has run_seq 0; the agent's events start at 1 and increase by 1; every run ends with RUN_FINISHED or RUN_ERROR Our extension
  • Subagent work stays in the current run: SUBAGENT_STARTED, SUBAGENT_FINISHED, SUBAGENT_ERROR and subagentRunId on events from an off-the-shelf AG-UI runtime are accepted and forwarded as usual, not rewritten into another form
  • The backend sends RUN_ERROR when an agent goes silent Our extension
  • The stop endpoint accepts an optional subagent_run_id: with it, only that subagent invocation stops, the agent closes it with SUBAGENT_ERROR whose code is "cancelled", and the run goes on Our extension
  • cancelRun (with the optional subagentRunId), loadActiveRuns and loadRunEvents are implemented, and stopping needs no conversation; for the Agent panel also loadAgentRuns, open according to your application's rules
  • Tool arguments and results are pushed according to the agent owner's setting Our extension
  • Every event of every run is kept, and a finished run can be fetched by run_id Our extension
  • The final reply carries metadata.run_id Our extension