接入自有后端
为你自己的 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 后端会采用同样的形状。规则本身见实时与同步。
后端要做的事
- 派发时生成
run_id。 把触发消息派给 Agent 时生成run_id,记下它属于哪个会话、哪个 Agent,随消息一起交给 Agent,同时推一个排队帧(run_seq为0,queued: true)。 - 只按
run_id路由。 收到 Agent 上报的事件,按run_id的绑定找到会话;没有run_id、run_id不认识或不属于这个 Agent、事件里的threadId与绑定不一致的,都拒收。Agent 做派发消息以外的工作时,先调申请运行;交给子 Agent 的工作不用申请,留在当前运行里,带subagentRunId。 - 推
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关闭这次调用,运行继续 我们的扩展,见停止运行。
- 接收者和消息相同:
- 提供参考接口:申请运行、上报、停止、两个快照、按运行取事件,见参考接口。第二期,发卡接口接受
run_id、tool_call_id、expires_at,答案作为那次工具调用的结果交回 Agent。 - 最终回复带
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我们的扩展
