OpenMax
免费试用

接入自有后端

为你自己的 API 写一个 ChatHost:手写对接后端的三个必填能力和会话列表,其余交给 createLocalPorts;再接上 Agent 运行的事件和接口。

接入自有后端

组件只从宿主(ChatHost 对象)取数据。你手写对接服务器的能力:必填的 identity、messaging、inboundDelivery,以及会话列表用的 conversations(可选,但渲染 ConversationList 时缺了会抛错)。其余六个必填能力(草稿、附件、渲染、提示、文案、实例作用域)由 @openmaxai/chat-sdk/react 的 createLocalPorts 补齐,必填一共九个,见能力。宿主标成 ChatHostWithConversationList,漏了 conversations 编译就不通过。会话里有 Agent 时,再按 Agent 运行一节接上运行事件。本页末尾有一份检查清单。

能力 做什么
identity 当前用户、查成员、搜通讯录
messaging 发消息、分页加载消息、新建会话
inboundDelivery 实时连接的参数,SDK 用它建连;演示宿主经 subscribe 推信号
conversations 会话列表:列出、置顶、隐藏(可选;渲染 ConversationList 时必须有)

一个完整的宿主

下面是一个精简的内存宿主,把内存数组换成你的 API 调用即可。

src/my-host.ts

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

const ME = "me";
const people: ChatParticipant[] = [
  { memberId: ME, displayName: "我", 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, // 信号由你自己通过 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: "zh-CN",
    }),
  };
}

// 服务端推来「会话 X 有新消息」时:
export function onServerPush(conversationId: string) {
  for (const notify of subscribers) notify({ kind: "messages", conversationId });
}

和 createChatHost 造的宿主一样,用 <ChatProvider host={host}> 安装,写法见安装。 宿主缺能力的输入框插件不会装上,例如没有 workItems 就没有 #,见能力。

手写宿主只能配 @openmaxai/chat 的组件(ConversationList、MessageThread 等):CwsConversationList、CwsMessageThread、ConversationHeader 这些 SDK 组件要读 createChatHost 宿主才有的内部件,装手写宿主时一渲染就抛错。 @openmaxai/chat 的组件不带样式根:@openmaxai/chat-sdk/styles.css 只作用在 SDK 组件自带的 .omx-chat 组件根之内,ChatRoot 本身不是样式作用域,所以它们渲染出来没有样式。要你把它们放进 ChatRoot,再在外面包一层带 omx-chat 类的元素(深色时另加 omx-dark,并给 ChatRoot 传 colorScheme="dark"),或者自己出样式。只包一层不够:对话框、菜单、浮层不在 ChatRoot 里时落到 document.body,在你包的那层之外,拿不到样式;在 ChatRoot 里时它们落在 ChatRoot 带 omx-chat 类的落点上。 想直接用带样式的 SDK 组件,改写一个适配器交给 createChatHost,见适配器 API。

容易写错的地方

消息格式。 ChatMessage 和 ChatConversation 由 SDK 定义,字段名与 OpenMax 相同,需要把你的数据映射过去,字段见数据模型。 每条消息都要有 seq:会话内唯一且递增的整数,排序和补洞都靠它。漏掉的字段一般不报错,只是界面少显示内容。见已知限制。

身份是同步读的。 currentUserId()、getMember()、listMembers() 返回值而不是 Promise。渲染前先拿到数据, 或自己缓存,数据到了给 ChatProvider 换一个新 host 对象(连同新的 identity)。在那之前,你的消息会显示成别人发的。

分页。 loadThread 沿不透明游标往更早翻;服务端说还有就返回 nextCursor,哪怕这页条数不够。 loadThreadSince(id, seq) 只返回 seq 更大的消息,没有返回 []。

实时信号。 subscribe 推 { kind: "messages", conversationId } 这类信号,消息区收到后调 loadThreadSince 拉取。 其他信号有 reconnected、reaction、messageChanged(别人编辑、撤回或审核删除了一条;编辑后的正文由消息区经 loadMessage 取)、read、delivery、card,各自的字段见实时与同步。每次重连成功后推 { kind: "reconnected" },告知界面连接已恢复。 实时连接归 SDK:isMock() 为 false 时 SDK 按 endpointUrl()、authToken()、clientId() 自己建连。上面的内存宿主是演示用的,所以 isMock() 返回 true、自己推信号。应用迁移期间如果还留着自己的连接,可以经 subscribe 把那条连接的信号转进来,这时 SDK 不另建连接;去掉自己的连接后,subscribe 也一起去掉。

被拦下的消息。 服务端内容过滤拦下消息时,sendMessage 返回 { blocked: { refusalText } },而不是抛错。消息区会在本地保留它并显示你的说明。

片段引用与撤回。 消息的 metadata 原样存、原样返回,片段引用(metadata.quote_excerpts)就能用。被引消息撤回后,界面只在知道被引消息已撤回的地方藏起片段;片段原文仍留在引用方那条消息上,经你的接口读到的人照样看得到。要抹掉它,把 message_id 是被撤回消息的条目改写成 { message_id, recalled: true },再推 messageChanged(change: "edited",messageId 是引用方那条),不要给它打 edited_at(它没有被编辑)。

上传

给 createLocalPorts 传上传函数,只负责搬字节并返回附件 id;任务列表、进度、取消和数量限制由 SDK 处理。

...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 },换不出地址的 id 直接不返回
  },
}),
  • 调用 progress(loaded, total),否则任务停在 0%;服务端收完字节后还要处理时调用 finalizing()。
  • 不传 attachments 就没有附件按钮;不传 resolveUrls,收到的附件显示为不可用。
  • conversationId 是 undefined:界面发起上传时不带会话。接口需要会话 id 的话,在 ChatProvider 里面给每个打开的会话再包一层 @openmaxai/chat/host 的 ChatHostProvider, 其 attachments 来自闭包里带会话 id 的上传函数,其余能力沿用外层 host(OpenMax 宿主的 ConversationScope 也是这样实现的)。ChatHostProvider 不是安装入口,只替换它下面这一块界面用到的能力。

替换其他本地能力

给 createLocalPorts 传 ports,替换六个本地能力中的任何一个:

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、链接、@ 提及
  },
}),

默认 render 把 Agent 回复按 Markdown 画(见 createMarkdownRender),其余文本显示保留换行的纯文本、链接化 http(s) 地址、画出 @ 提及。 默认 attention 什么都不做,不替换的话用户看不到错误提示。

可选能力

往 host 上加可选字段(如 mentions、profileCard、cards、groupManagement,以及 messaging 上的表情回应、撤回、编辑等方法)即可打开更多功能。 表情回应、撤回、编辑这几个方法成功时可以返回 { changeSeq }(后端给这次改动的编号时),不给就返回 void;服务端明确不允许时抛 kind 为 forbidden 的 ChatSdkError(new ChatSdkError("forbidden", message),从 @openmaxai/chat-sdk 引入),撤回、编辑时界面据此提示「无法撤回 / 无法编辑」。 每项打开什么、缺了会怎样见能力,每个成员的签名和出错约定见宿主能力。

Agent 运行

规划中

要在会话里显示 Agent 的运行进度、工具步骤和停止按钮,SDK 需要两样东西:实时收到的 Agent 事件,和宿主上 agentRuns 能力的方法(停止、取会话的运行快照、按 run_id 取一次运行的事件,以及 Agent 面板用的取 Agent 的运行快照)。线上的帧和接口怎么设计由你决定,下面给的是参考形状,OpenMax 后端会采用同样的形状。规则本身见实时与同步。

后端要做的事

  1. 派发时生成 run_id。 把触发消息派给 Agent 时生成 run_id,记下它属于哪个会话、哪个 Agent,随消息一起交给 Agent,同时推一个排队帧(run_seq 为 0,queued: true)。
  2. 只按 run_id 路由。 收到 Agent 上报的事件,按 run_id 的绑定找到会话;没有 run_id、run_id 不认识或不属于这个 Agent、事件里的 threadId 与绑定不一致的,都拒收。Agent 做派发消息以外的工作时,先调申请运行;交给子 Agent 的工作不用申请,留在当前运行里,带 subagentRunId。
  3. 推 agent_event 帧。 在聊天的同一条 WebSocket 上推,格式见实时与同步:
    • 接收者和消息相同:run_id 绑定的那个会话的成员和旁观者,不推给别的会话;这个 Agent 的全部运行(包括不绑定会话的)另推给正在看它的 Agent 面板、且你的应用允许看的人。
    • permissions 按接收者分别填:给运行的发起人和 Agent 的主人 cancel: true(没有发起人的运行只给主人;你的应用可以按自己的规则再加人)。
    • TOOL_CALL_ARGS、TOOL_CALL_RESULT 按 Agent 主人的配置推给接收者;主人旁观时推给主人。
    • 同一运行内按 run_seq 顺序推,重推同一个 run_seq 是安全的。
    • event 转发时不增删字段,仍是合法的 AG-UI 1.0 事件;我们自己的信息只放在外层。
    • 兜底收尾:Agent 长时间没有事件时,后端代为推一个 RUN_ERROR,免得界面一直显示「正在执行」。我们的扩展
    • 停止:收到停止请求时通知 Agent。只停一次子 Agent 调用时,Agent 以 code 为 "cancelled" 的 SUBAGENT_ERROR 关闭这次调用,运行继续 我们的扩展,见停止运行。
  4. 提供参考接口:申请运行、上报、停止、两个快照、按运行取事件,见参考接口。第二期,发卡接口接受 run_id、tool_call_id、expires_at,答案作为那次工具调用的结果交回 Agent。
  5. 最终回复带 metadata.run_id。 Agent 的最终回复照常作为消息发送,界面靠它把运行摘要挂到回复上。

第一期不需要 SSE。以后可能为外部集成另加一个 AG-UI 标准的 SSE 端点,推的是同样的事件,经一层翻译处理我们对 AG-UI 1.0 的扩展。

交给 SDK 的信号

宿主把 agent_event 帧翻成 ChatAgentEventSignal。event 的类型是 AG-UI 1.0 的事件联合,@openmaxai/chat 依赖 @ag-ui/core 1.0.x,并以 AgUiEvent 的名字转出这个类型,你不用自己装 @ag-ui/core:

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

interface ChatAgentEventSignal {
  kind: "agentEvent";
  /** 不绑定会话的运行(只在 Agent 面板出现)没有。 */
  conversationId?: string;
  agentMemberId: string;
  runId: string;
  /** 运行内序号:排队信号为 0,之后从 1 开始,每个事件加 1。 */
  runSeq: number;
  /** 运行在排队,此时没有 event。 */
  queued?: boolean;
  triggerMessageId?: string;
  /** 当前用户对这次运行能做什么。 */
  permissions?: { cancel?: boolean };
  /** AG-UI 1.0 事件,转发时不增删字段(子 Agent 的事件带 subagentRunId)。排队信号没有。 */
  event?: AgUiEvent;
}

手写宿主从 inboundDelivery.subscribe 推这个信号,和其他信号走同一个回调;agentRuns 挂在宿主上:

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

export function createMyHost(api: MyApi): ChatHostWithConversationList {
  return {
    // identity、messaging、inboundDelivery、conversations……同上文
    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)),
    },
  };
}

// WebSocket 收到 agent_event 帧时:
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 必需的方法是 cancelRun、loadActiveRuns 和 loadRunEvents,可选的是 loadAgentRuns 和 describeTool。去重、排序、缺号补齐、什么时候取快照都由通用层做,宿主只负责翻译。

参考接口

我们的扩展

下面的路径和字段是设计稿,代码里还没有,名字可能调整。这些接口都是我们的,AG-UI 1.0 没有对应:它只描述事件流,不规定申请运行、上报、停止和补取的接口。

申请运行

Agent 做派发消息以外的工作时调用。交给子 Agent 的工作不用申请,它留在当前运行里。二选一:

  • 带会话(主动工作):后端检查 Agent 是这个会话的成员,把运行绑定到这个会话,同时向会话推这个运行的排队帧。
  • 不带会话(定时任务、维护工作等):运行不绑定会话,只在 Agent 面板出现。响应里的 thread_id 是这个 Agent 的线程 id,Agent 在这次运行的事件里用它作 threadId。
POST /api/v1/agent-runs

带会话:

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

不带会话:

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

两种运行都没有发起人,只有 Agent 的主人能停止。

Agent 上报事件

Agent 攒一批事件,用一次请求报上来。路径里没有会话:会话由每个事件的 run_id 决定。

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" }
    }
  ]
}
  • 只接受后端发给这个 Agent 的 run_id;一批里可以有几个会话的运行。
  • 同一运行内按 run_seq 升序;后端按 run_id + run_seq 去重,所以整批重发是安全的。
  • 成功返回 202,之后按 run_id 逐个推给对应会话里的人。

停止运行

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

请求体可以为空,表示停止整次运行;只停一次子 Agent 调用时带上它的 id 我们的扩展:

{ "subagent_run_id": "sa_1" }
  • 路径里没有会话:run_id 由后端生成,后端知道它绑定了哪个会话,不绑定会话的运行也用同一个接口。
  • 成功返回 202:后端已经通知 Agent 停止。停整次运行时,Agent 先关闭还开着的子 Agent 调用,运行随后以 outcome 为 cancelled 的 RUN_FINISHED 收尾。带 subagent_run_id 时,Agent 以 code 为 "cancelled" 的 SUBAGENT_ERROR 关闭这次调用和它开出的子调用,运行继续。
  • 没有权限返回 403。运行已经结束,或要停的子 Agent 调用已经结束时返回 409,界面按已结束处理。这次运行里没有这个子 Agent 调用时返回 404。
  • 停止正在 Agent 主会话里执行的运行,可能连带打断主会话,见消息区。
  • 运行的发起人和 Agent 的主人可以停止,整次运行和其中的子 Agent 调用都一样;没有发起人的运行只有主人能停。

运行快照

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" } }
      ]
    }
  ]
}

会话快照返回这个会话里所有还没结束的运行(包括排队中的,排队中的 events 为空并带 "queued": true),每次运行带到目前为止的全部事件。已结束的运行不返回。

Agent 面板用另一个快照,返回这个 Agent 所有还没结束的运行,包括不绑定会话的,形状相同。谁能调由你的应用决定:

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

按运行取事件

按 run_id 取一次运行的外层字段和事件,不管运行是否已经结束。客户端在三种情况下调用:run_seq 缺号;仓库里没结束的运行从新取的快照里消失了(多半是收尾那一帧漏了);展开一次已结束的运行。规则见实时与同步。

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 可以不带,不带时返回全部事件。
  • 运行不存在或当前用户无权查看时返回 404,客户端把这次运行从仓库里移除。
  • 不绑定会话的运行没有 conversation_id;谁能取由你的应用决定,规则和 Agent 面板相同。

回答审批卡

第二期。作答用卡片按钮的作答请求,不新增接口。卡片带 tool_call_id 时,后端把答案作为那次工具调用的结果交给 Agent;卡片过了 expires_at 再作答时返回过期错误,宿主把它折成 window-expired。见交互卡片。

适配器 API

适配器 API 把同步身份缓存、列表失效、上传绑定会话这些手写宿主要处理的事收进 SDK。 你只写一个 ChatSdkAdapter 对象(identity.me()、members()、messaging、conversations、realtime.connect(sink)、uploads.upload() 等异步函数), 交给 @openmaxai/chat-sdk 的 createChatHost({ adapter })。能力随字段是否存在而定:不写 realtime 就没有实时更新,不写 uploads 就没有附件按钮。 没有后端时可以先用 @openmaxai/chat-sdk/testing 的内存适配器把界面跑起来,见测试;一致性测试套件还没有。

每个成员的签名、必填与否和出错约定见适配器接口;失败时抛 ChatSdkError,种类见错误模型。一个只有必填成员和实时的适配器:

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 代表你自己的后端客户端:AcmeApi 接口、它的实例 api、toSignal(把一帧 socket 消息翻成信号,例如 { kind: "messages", conversationId })和 redirectToLogin。

这个宿主和快速开始里的一样用:SDK 组件放在 ChatRoot 里,全局 CSS 引入 @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>
  );
}

在数据层里,适配器只做三件事:保持连接,把服务端的帧翻成事件,每次重连成功后发 reconnected;提供 loadThread(按游标往更早翻)和 loadThreadSince(取某个 seq 之后的消息)两个读接口;发送时把 clientMessageId 交给后端,并在读回的消息上带回。 缓存、去重、什么时候补洞、本机存储都归通用层里的仓库包,适配器不要自己做,见 @openmaxai/chat-store。

Agent 事件也一样:在 realtime.connect(sink) 里把 ChatAgentEventSignal 交给 sink,agentRuns 写在适配器上,SDK 把它包成宿主的能力。规划中

标了「规划中」的那条(Agent 事件)代码里还没有。规划中

检查清单

消息

  • 每条消息都有整数 seq,会话内从 1 递增、不重复
  • currentUserId()、getMember()、listMembers() 同步返回;身份数据到达后换一个新的 host 对象
  • loadThread 沿游标往更早翻,服务端说还有就返回 nextCursor;loadThreadSince 只返回 seq 更大的消息,没有时返回 []
  • subscribe 推 messages 等信号,每次重连成功后推 reconnected
  • 被内容过滤拦下的消息返回 { blocked: { refusalText } },不抛错
  • 上传调用 progress,换地址时换不出的 id 不返回
  • 发送时把 clientMessageId 交给后端作为去重键(同一个键重发不写第二条),并在读回的消息上作为 client_msg_id 原样带回
  • 要支持从链接按 id 打开会话时提供 conversations.loadConversation:会话不存在或无权访问返回 undefined,不抛错 规划中
  • 提供 conversations.loadUnreadTotal 时,免打扰和只是旁观的会话不计入 规划中
  • render.renderMessageText 把文本消息的正文按 Markdown 画(人发的消息也是 Markdown),@ 提及和链接照常 规划中

Agent 运行

规划中

标「我们的扩展」的条目是 AG-UI 1.0 之外我们自己的约定;其余是 AG-UI 1.0 本身的规则,或 SDK 能力的要求。

  • 派发消息时生成 run_id 并绑定会话,推排队帧 我们的扩展
  • 只按 run_id 路由;没有 run_id 或 threadId 与绑定不一致的事件拒收;不绑定会话的运行只推给 Agent 面板 我们的扩展
  • agent_event 帧只推给绑定会话的成员和旁观者,permissions 按人填写(cancel 给发起人和主人,没有发起人时只给主人) 我们的扩展
  • 事件里的 threadId、runId 与外层 conversation_id、run_id 一致 我们的扩展
  • 排队帧的 run_seq 为 0;Agent 的事件从 1 开始连续递增;每次运行以 RUN_FINISHED 或 RUN_ERROR 收尾 我们的扩展
  • 子 Agent 的工作留在当前运行里:现成 AG-UI 运行时发出的 SUBAGENT_STARTED、SUBAGENT_FINISHED、SUBAGENT_ERROR 和事件上的 subagentRunId 照常接受和转发,不改写成别的形式
  • Agent 失联时后端补发 RUN_ERROR 我们的扩展
  • 停止接口接受可选的 subagent_run_id:带了只停这一次子 Agent 调用,Agent 以 code 为 "cancelled" 的 SUBAGENT_ERROR 关闭它,运行继续 我们的扩展
  • cancelRun(含可选的 subagentRunId)、loadActiveRuns、loadRunEvents 已实现,停止不要求会话;要做 Agent 面板时还有 loadAgentRuns,按你的应用的规则开放
  • 工具参数和结果按 Agent 主人的配置推送 我们的扩展
  • 保留每次运行的全部事件,已结束的运行也能按 run_id 取回 我们的扩展
  • 最终回复带 metadata.run_id 我们的扩展