OpenMax
免费试用

实时与同步

服务端的变化怎么推到客户端:实时信号、Agent 事件帧,以及 seq 与水位、时间字段、补洞时刻、去重、缺号、重连、运行快照和按运行取事件。

实时与同步

消息和 Agent 运行走同一条实时连接,漏了也按同一套时刻补齐。区别只在序号:消息用会话内的 seq,运行事件用运行内的 run_seq。

实时信号

实时连接归 SDK:SDK 按宿主 inboundDelivery 给的地址、令牌和客户端 id 建连,收到服务端的帧后把它翻成信号交给组件。应用不再自己另开一条连接。

信号 含义 组件怎么做
{ kind: "messages", conversationId } 这个会话有新消息 调 loadThreadSince 从已有的最大 seq 往后取
{ kind: "reaction", conversationId, messageId, reactorId, code, added, changeSeq? } 某人加上或撤掉了一个表态 更新那条消息的表态
{ kind: "messageChanged", conversationId, messageId, change, changeSeq?, recalledByRole? } 某人编辑(edited)、撤回(recalled)了一条消息,它被审核删除(deleted),或有人答了一张卡(card) edited:这一窗里有这条时,用 loadMessage 按 id 取回新正文;card:同样按 id 取,只取卡片那几格(已显示的结果行不会被清掉);recalled:画成「已撤回」(recalledByRole: "admin",即帧里的 recalled_by_role,写「管理员撤回了一条消息」、不写名字;其余按发送人写);deleted:整条去掉,不留「已撤回」
{ kind: "read", conversationId, memberId, readUntilSeq } 某人的已读位置前进了 更新已读回执
{ kind: "delivery", conversationId, ackUntilSeq } 会话的送达位置前进了 更新送达状态
{ kind: "card", conversationId, messageId, fields } 一张卡片的内容或结果(card_state)变了 更新那张卡片
{ kind: "reconnected" } 连接已恢复 重新补齐;连接状态回到 connected
{ kind: "connected" }(可选) 连接第一次连上 重取一次会话列表、把开着的会话补一次;不清在线状态、不重读资料
{ kind: "disconnected" } 规划中 连接断开,正在重连 连接状态变为 reconnecting,见 ChatInboundDisconnectedSignal
{ kind: "typing", conversationId, memberId, active } 某人开始或停止输入(ChatInboundTypingSignal)。可能是当前用户自己(服务端也发回给发送者) 消息区不动作;Chat SDK 的会话头部更新正在输入(读的时候滤掉自己);active 为 true 后 6 秒没有新的就当作停止
{ kind: "presence", memberId, status, lastSeenAt? }(Chat SDK 自有,不交给 @openmaxai/chat 的组件,见 ChatSdkPresenceSignal) 某个成员上线 / 下线(组织级) Chat SDK 的会话头部在 Agent 单聊里更新对端在线状态;重连时先清掉记下的状态,再重读一次成员资料

每次重连成功后推 { kind: "reconnected" },告知界面连接已恢复;断开时推 { kind: "disconnected" },心跳不推。规划中messages 信号不带消息正文,正文总是从 loadThreadSince 取。用 createChatHost 时,连接地址就是 wsUrl。

自己的表态、编辑、撤回不等信号:界面先改,请求成功时宿主可以交回这次改动的编号(ChatMessageChangeResult 的 changeSeq),消息仓库据此认出随后到达的同一次改动的推送。别人的改动走 messageChanged:它只说哪一条、改了什么,不带正文,所以宿主没有 loadMessage 时,别人的编辑要等重新加载这段消息才出现。reaction、messageChanged 带的 changeSeq 是服务端改动日志的编号,旧服务端的帧没有它,就不给。

离线、切走期间别人对已有消息的改动按改动日志补回:宿主提供 loadChangesSince 和 getMessagesByIds、一窗带 headChangeSeq 时,重连和切回会话的补洞补完新消息接着补改动(createChatHost 造的宿主已接上)。推送的改动编号跳了号时,过 1.5 秒再补改动;没进仓库的那几声(窗外的编辑 / 撤回、取数失败)不带编号,改动水位停在它前面,等下一笔推送或下一次补洞补上。

宿主转发信号是过渡用的:应用迁移期间还持有自己的连接时,把那条连接的帧翻成同样的信号,经 inboundDelivery.subscribe(onSignal) 转给组件,这时 SDK 不另建连接,因为同一设备 id 的两条连接会互相覆盖同步位置。应用迁移期间还持有自己的连接、又没有接 openMaxSharedRealtime 时,才走这种转发;接了借用端口以后就不再转发。演示宿主(isMock() 为 true)也经 subscribe 推信号,见接入自有后端。

页面上一条连接,归谁持有分两档:

  • 宿主已有自己的连接:连接、换票、设备标识、断线重连与回前台恢复、sync 回执都归宿主那条连接;接 OpenMax 时适配器给 realtime: "off",再用 openMaxSharedRealtime 把那条连接收到的原始帧交给 SDK。帧的解码与翻译仍在适配器包里、只有一份,SDK 不另建连接、不回执,每次连上收到一声 reconnected。
  • 没有自己的连接(一般的外部接入方):给 wsUrl,适配器自己换票、建连、退避重连;storage: "localStorage" 且设备标识写进去读得回时,它也回执 sync(有 has_more 先翻页),默认 "memory" 不回执。

应用自己的连接同时服务聊天以外的部分(在线状态、通知、Agent 执行过程)时走第一档:聊天 SDK 借用它,不另开一条,这条连接仍是应用自己的实时模块。

序号

消息 运行事件 规划中
序号 seq:会话内从 1 递增、不重复 run_seq:运行内序号,排队帧为 0,Agent 的事件从 1 开始,每个加 1
持久吗 是,消息存在后端 运行事件是临时的,只推送;只有最终回复作为消息占 seq
有序的范围 一个会话内 一次运行内(子 Agent 调用的事件也在其中,共用一个 run_seq 序列);不同运行之间没有先后关系
漏了怎么补 从水位往后调 loadThreadSince 缺号时按运行取事件;打开会话等时刻取运行快照

agent_event 帧

规划中 我们的扩展

运行事件经聊天的同一条 WebSocket 推送,装在一种新帧 agent_event 里,鉴权、旁观者、多端推送都沿用聊天的规则。外层是我们自己的字段,AG-UI 1.0 没有对应;event 里放一个 AG-UI 1.0 事件,转发时不增删字段(AG-UI 的事件对象不允许多余字段,所以我们自己的信息都放在外层):

{
  "type": "agent_event",
  "id": "f_01J9Z3",
  "timestamp": 1759590000123,
  "payload": {
    "conversation_id": "c_123",
    "agent_member_id": "m_agent",
    "run_id": "r_456",
    "run_seq": 3,
    "trigger_message_id": "msg_789",
    "protocol_version": "1.0",
    "permissions": { "cancel": true },
    "event": {
      "type": "TOOL_CALL_START",
      "toolCallId": "t_1",
      "toolCallName": "web_search",
      "parentMessageId": "msg_789"
    }
  }
}

type、id、timestamp 与聊天的其他帧相同,其余外层字段也和其他帧一致。下表 * 表示每一帧都有,其余字段可以没有:

payload 字段 说明
conversation_id 后端按 run_id 的绑定填写,等于事件里的 threadId;不绑定会话的运行(只在 Agent 面板出现)没有这个字段
agent_member_id* 这次运行属于哪个 Agent(成员 id)
run_id* 运行 id,等于事件里的 runId
run_seq* 运行内序号:排队帧为 0,Agent 的事件从 1 开始,每个加 1
queued 只出现在 run_seq 为 0 的帧上,值为 true,表示运行在排队;这一帧没有 event
trigger_message_id 触发这次运行的消息;定时任务等没有触发消息的运行没有
protocol_version* event 所用的 AG-UI 版本,值为 "1.0"
permissions 收到这一帧的人对这次运行能做什么,如 { "cancel": true }。服务端按接收者分别填,同一次运行不同人收到的值可以不同;没有等于什么都不能做
event AG-UI 1.0 事件对象,转发时不增删字段;只有排队帧没有

事件里带 threadId 或 runId 时,必须与外层的 conversation_id(不绑定会话的运行是后端发的 Agent 线程 id)、run_id 一致;不一致的帧丢弃。收到不认识的事件类型或字段时,客户端忽略它,不报错。子 Agent 的事件带 subagentRunId,外层不另加字段。

宿主把这一帧翻成 ChatAgentEventSignal,和其他信号走同一个 subscribe 回调,见接入自有后端。

时间

规划中

规则只有一条:时间点跟着它所在的那份数据的既有写法走,Agent 运行新增的时间一律用整数毫秒(Unix 纪元起)。

字段 写法 为什么
agent_event 帧的 timestamp 整数毫秒 和聊天其他帧的 timestamp 相同
ChatAgentRun 的 startedAt / endedAt,工具调用的 startedAt / endedAt 整数毫秒 Agent 运行新增,按上面的规则
每个 AG-UI 事件的 timestamp 整数,我们要求毫秒 我们的扩展 AG-UI 1.0 定为整数、没有规定单位,各家 SDK 实际都用毫秒
Interrupt.expiresAt(第二期) ISO 8601 字符串,如 "2026-10-05T10:00:00Z" AG-UI 1.0 的约定
卡片的 expires_at(第二期) ISO 8601 字符串 一一对应 Interrupt.expiresAt,也和卡片的 created_at、result_at 一致

界面算用时用外层帧的 timestamp 和收到的顺序,不依赖 AG-UI 事件里可有可无的 timestamp。

补洞

规划中

规划中的消息仓库在四个时刻从水位往后补,你和适配器都不用判断:

  1. 打开会话;
  2. 切回一个打开过的会话;
  3. 实时连接重连成功,即适配器发出 reconnected;
  4. 页面从后台回到前台。

补洞的规则:

  • 同一会话不并发。 一个会话正在补时,又到了一个补洞时刻或 messages 信号,等这一次补完再从新的水位补一次,不同时发两个请求。
  • 按服务端说的收工。 反复调 loadThreadSince,直到返回的 ChatThreadSincePage 带 hasNewer: false;返回的是数组时,直到返回空数组。
  • 最多 10 轮。 10 轮之后服务端仍说还有,仓库取一次最新一窗。这一窗和内存里的窗口接得上(对方一直在发、每一轮都有新的,其实没有缺口)时接在窗口后面,正在看的那几行不动;接不上说明离开太久、缺口太大:仓库丢掉这个会话在内存里的窗口,换成最新一窗,从那里接着显示;更早的消息往上翻时再取。
  • 窗口没接到最新时不补进窗口。 围着某条消息取的一窗、或往上翻卸掉了新端时,messages 信号只记下有新消息(给「有新消息」的提示用),不把新消息补进窗口;窗口接到最新以后照常补。

适配器没有 loadThreadSince 时不补洞,漏掉的消息要等重新加载会话才出现。在同样的四个时刻,仓库还取一次运行快照(agentRuns.loadActiveRuns),并对账结束的运行。

运行事件的顺序与缺号

规划中

  • 同一运行内严格有序。 客户端按 run_seq 依次处理。
  • 去重。 run_id + run_seq 已经处理过的帧直接丢弃,所以服务端重发是安全的。
  • 缺号。 收到的 run_seq 比已处理的大不止 1 时,客户端先把这一帧暂存,按 run_id 取这次运行在已处理序号之后的事件(agentRuns.loadRunEvents)补齐,再接着处理。绑定会话和不绑定会话的运行都这样补。
  • 不占水位。 运行事件不进会话的 seq,不移动水位。
  • 收尾。 收到 RUN_FINISHED 或 RUN_ERROR 后,这次运行不再接收事件。Agent 长时间没有动静时,服务端代为发一个 RUN_ERROR 收尾,界面不会一直显示「正在执行」或「排队中」。我们的扩展

去重、排序、缺号补齐、什么时候取快照都由通用层(@openmaxai/chat-store)做,宿主和适配器只负责把帧翻成信号。

运行快照

规划中 我们的扩展

打开会话时(包括刚被拉进会话的成员和旁观者),以及上面的四个补洞时刻,客户端经 agentRuns.loadActiveRuns 取运行快照:这个会话里所有还没结束的运行(包括排队中的),每次运行带外层字段和到目前为止的全部事件(各带 run_seq)。客户端把快照里的事件和实时帧经同一个入口处理,按 run_seq 去重,之后只接收序号更大的帧。

Agent 面板打开时取另一份快照(agentRuns.loadAgentRuns):这个 Agent 所有还没结束的运行,包括不绑定会话的。接口形状见接入自有后端。

已经结束的运行不在快照里。最终回复通过 metadata.run_id 关联到运行。

快照里消失的运行

运行结束的那一帧可能正好在断线期间漏掉,而快照只返回还没结束的运行,所以单靠快照,界面会一直显示「正在执行」。规则:

  • 仓库里还没结束的运行,如果不在新取的快照里,就按 run_id 调 agentRuns.loadRunEvents,从已处理的 run_seq 往后取,收尾事件(RUN_FINISHED 或 RUN_ERROR)随之补上。
  • 会话快照和 Agent 面板的快照都按这条规则对账;不绑定会话的运行只能这样补。
  • 取不到(运行不存在或当前用户无权查看)时,把这次运行从仓库里移除,不留在「正在执行」。

按运行取事件

我们的扩展

服务端保留每次运行的全部事件,不只是摘要。agentRuns.loadRunEvents 按 run_id 返回一次运行的外层字段和事件,不管运行是否已经结束。它有三个用处:缺号补齐、对账快照里消失的运行,以及刷新页面或换设备之后展开已结束的运行看工具步骤(消息仓库在你展开时按需取回)。接口形状见接入自有后端。

多个标签页与多端

同一用户的每个设备、每个标签页都各自收到同样的帧。第一期每个标签页各自连接、各自补洞;打开 IndexedDB 时只有拿到单标签页锁的那个标签页写本机数据,其他标签页用内存。第二期由一个主标签页持有连接、其他标签页共用。

realtime: "off" 时不建连,别人的新消息和卡片结果都不会自动出现。