支持的协议

Umo Editor Next 的消息传输能力支持 自定义协议模式 与 AG-UI 标准协议模式。

AG-UI 协议更多信息见：https://docs.ag-ui.com/introduction

在 Umo Editor Next 中，协议选择来自 ai.models[].protocol：

• protocol: 'default'：自定义协议模式（由 ai.callbacks.onMessage 把后端 chunk 映射为组件内容块）
• protocol: 'agui'：AG-UI 标准协议模式（交给组件内置解析）

协议选择逻辑：编辑器会根据当前模型的 protocol 决定是否走自定义解析（ai.callbacks.onMessage）或交给 AG-UI 内置解析。

OpenAI 协议

Umo Editor Next 中的 protocol 只用于描述 前端与“后端 SSE 服务”之间 的数据协议（default / agui），并不等同于 “OpenAI Chat Completions / Responses API 协议”。

如果希望接入“遵循 OpenAI 兼容协议”的主流大模型（许多厂商提供 OpenAI-compatible endpoint）：

• 推荐做法：在后端实现一个 适配层/代理：前端的 default 或 agui 协议访问后端，后端再去调用 OpenAI 兼容接口，并把返回转换为 SSE 事件回推给前端，可以参考或直接调用 Umo Editor Server 中的 AI 服务代理接口 接口。
• 不推荐：浏览器端直连 OpenAI 兼容接口（会暴露密钥、且常见 CORS 限制）。

具体接入示例见 后端示例。

默认协议

适用场景

• 已有后端接口，返回数据结构难以改造成 AG-UI
• 只需要“文本 / Markdown / 思考态”等基础能力，不需要工具调用、状态机等复杂事件
• 希望快速落地：只要返回标准 SSE，前端通过回调进行映射即可

常见坑位

• chunk 的 JSON 必须是单行可解析：如果在 data: 后直接输出含换行的 Markdown，SSE 解析会被拆断；请改为 JSON 字段里用 \n 表达换行。
• 必须及时 flush：很多框架默认缓冲输出，会导致前端一直不显示“流式”；需要禁用缓冲或显式 flush。
• 正确的响应头：Content-Type: text/event-stream，并通常需要 Cache-Control: no-cache、Connection: keep-alive。
• CORS：浏览器环境下跨域 SSE 常见失败点；务必允许 Authorization、Content-Type 等自定义 header。

AG-UI 标准协议

适用场景

• 希望具备“工具调用、状态更新、多步骤任务”等更复杂的 agent 交互
• 愿意让后端按 AG-UI 事件类型输出（前端自动解析与渲染）

协议特点

• AG-UI 是为 AI Agent 与前端交互设计的轻量标准协议
• 通过标准化事件类型描述对话生命周期、文本消息、思考过程、工具调用、状态更新等
• 内置支持 AG-UI 协议的数据双向转换：符合协议的后端可直接接入

行为差异

当 models[].protocol === 'agui' 时：

• 不会走 ai.callbacks.onMessage 的自定义解析
• chunk 的解析交给内置的 AG-UI 解析器

因此：

• 必须确保后端输出的 SSE 事件符合 AG-UI 约定
• 需要在后端完成“把模型输出 / 工具调用”转换为 AG-UI 事件

如何选择不同协议

• 快速落地/最少改动：default + ai.callbacks.onMessage（控制映射逻辑）
• 需要工具调用/状态机/多步骤任务：agui（控制事件协议）