1. 为什么需要一个“智能体与用户之间”的协议1.1 MCP 解决了一半问题另一半卡在“人的界面”从 2024 年底开始做 AI 智能体AI Agent开发的团队几乎绕不开一个词MCP。它把“工具”这件事标准化了智能体要读取 GitHub 仓库、搜索 Notion 文档、查数据库、调用第三方 API只要在 MCP Server 里注册一下任何支持 MCP 的客户端都能直接调。这个设计确实把“模型连接外部世界”的门槛大幅降低到现在基本成了事实上的业界标准。但真正把智能体推到业务前线的团队很快会撞到另一堵墙智能体要执行敏感操作时怎么跟用户打交道我举个很常见的例子员工让智能体“把这周的销售数据整理成周报并邮件发给各区域负责人”这条任务链路里至少有三个地方必须让人介入智能体要读取包含客户信息的 Excel 文件需要先获得授权汇总完成后用户要检查周报内容是否正确点击发送之前用户要确认收件人列表和邮件正文没有错漏。这些动作不能静默执行。用户至少要知情、确认有时候还要在中间补充参数。但目前的 MCP 协议里对话链路是“模型 → 智能体运行时 → 工具”整个过程几乎没有给“人”留下标准化的位置。你可以自己在代码里硬编码一个确认弹窗也可以在某个前端框架里写一个私有模态框但这些都属于项目里的“私货”换一个客户端、换一个前端框架就要全部重写。1.2 AG-UI 想解决的问题把“人在回路”标准化AG-UI 要补的正是这一块智能体与应用之间关于“用户交互”的部分。它不是一个模型协议也不是 agent 编排协议而是一套描述“智能体如何在用户界面上发起和回收交互动作”的开放协议。你可以简单理解为MCP 管“智能体调用世界”AG-UI 管“智能体调用用户”。打个比方。MCP 像物流系统把货物从仓库送到你楼下AG-UI 则管签收、开箱、让你检查货物是否符合预期。没有签收环节快递永远只是“看起来送到了”没有用户交互协议智能体也只是“看起来把活干完了”。如果智能体执行的是删除文件、转账、发邮件这种不可逆操作缺少一个标准化的“人参与确认”环节业务方根本不敢放它上线。这里要特别强调一点AG-UI 并非要取代 MCP也不和 LangChain、Dify、Coze 这类平台冲突。它作用在更靠近应用层的位置目标是把“AI 智能体与用户应用之间的交互方式”做成公共标准让不同团队不再重复造轮子。这个协议由 Braintrust 等团队推动目前已经有一些开源实现和 SDK正在逐步被智能体应用开发者采用。1.3 适合谁、用在什么场景如果你属于下面这几类人AG-UI 值得你花时间研究做智能体应用前后端开发的工程师。Chatbot、Agent 服务只要涉及“用户确认”或“中途收集信息”就需要一套可靠的交互机制。智能体平台研发团队。自建 Agent 平台或者对 Dify、Coze 做二次开发的人需要把用户授权、审批、确认的交互做成标准能力而不是每次改一个界面就返工。做 RPA、浏览器自动化、桌面端自动化产品的人。自动化流程执行到关键步骤时必须把控制权交还给用户AG-UI 正好覆盖这个环节。企业数据助手、内部知识库问答等需要权限审批的场景。员工让智能体读取核心系统数据之前必须经过用户点击授权这个动作如果走标准协议审计和合规都会轻松很多。我自己的感受是AG-UI 本质上是在解决一个“最后一公里”的问题。模型能力强不强是一回事智能体能不能被用户信任是另一回事。没有标准的交互确认层再强的 Agent 都只敢在沙箱里玩一到真实业务就露怯。2. AG-UI 的核心设计与组件拆解2.1 核心概念UI Action 与运行时AG-UI 最核心的抽象是 UI Action也就是“用户界面动作”。它把智能体想要从用户那里获得的反馈统一封装成动作。我在实际项目里用过比较高频的几种类型requestPermission请求权限。比如读取本地文件、访问某个网页、调用外部 API都需要先向用户申请。prompt向用户提问。智能体运行到一半发现缺必要参数比如生成周报时不确定要按哪个语言输出就直接发一个提问动作。form收集结构化表单。需要用户同时提供多个字段时比如“目标城市”和“期望出发时间”用表单一次收齐。confirm确认类动作。删除文件、发送邮件、提交订单这类高风险操作必须让用户明确二选一。notify通知。把结果或中间状态展示给用户不要求用户反馈。这些动作并不是分散的弹窗组件而是由一套运行时Runtime来统一分发和处理。智能体端把 Action 发给运行时运行时负责把它路由到正确的 UI 组件UI 组件完成用户交互后再把结果通过运行时返回给智能体。整个过程是异步的用户的思考时间完全不受智能体执行速度影响。我在设计自己的系统时把 Action 看成一种特殊的 JSON-RPC 消息。动作里必须带一个全局唯一的 actionId因为用户在 UI 上确认需要时间智能体端可能已经跑到了下一个节点回执必须能对齐到对应步骤。没有这个 id整个消息流转根本没法追踪。2.2 AG-UI Web 与 RTUI 的分工AG-UI 协议体系里有两个容易混淆的名词AG-UI Web 和 RTUI。它们的边界很清晰但不少刚接触的人会搞混。按我自己的理解可以这么划分AG-UI Web 是前端侧的 SDK 和界面渲染层。它关注的是“把 Action 渲染成什么 UI 元素”“用户操作后如何返回结果”。比如一个 confirm 动作在前端可以被渲染成普通弹窗也可以被渲染成侧边栏卡片这是 SDK 的灵活之处。RTUI 是实时传输层。它关注的是字节和连接如何建立 WebSocket 通道、如何处理断线重连、消息如何编解码。RTUI 不关心 UI 组件长什么样只关心消息能不能稳定地从智能体端到达前端。用一张表格来对比会更清楚维度MCPAG-UI WebRTUI解决核心问题智能体调用外部工具智能体与用户的界面交互交互消息的实时传输消息方向Server 与 Client 之间Agent - UI - User - UI - Agent双向实时消息典型消息tools/callrtui/actionws 帧 / SSE 事件主要使用者开发者与 Agent 运行时前端 SDK传输层实现简单说RTUI 是 AG-UI Web 的底层传输底座。两者可以分开使用也可以配合使用。如果你只想做一套标准的用户确认流程不关心底层是 WebSocket 还是 SSE那直接上手 AG-UI Web 就够了。如果你的智能体跑在云端需要在边缘节点和 Web 前端之间建立低延迟通道那就得在 RTUI 上花点功夫。2.3 与主流 Agent 平台Dify、Coze 等的配合关系Dify、Coze 这类智能体编排平台目前已经把 MCP 工具接入做得相当成熟能快捷地让 Agent 调用各种 API。但“执行到一半需要用户确认”这个能力各家平台的实现方式依然千差万别有的是 Workflow 里的“人工审核”节点有的是会话交互里的特殊消息类型有的是你自己写插件去调用前端 SDK。结果就是你在 Dify 上做的一套确认流程搬到 Coze 上基本要重写。AG-UI 的价值在这里就体现出来了。如果平台侧把“请求用户授权”“等待用户确认”“收集用户输入”这些能力统一按 AG-UI 的方式暴露那么上层应用和前端 UI 就可以跨平台复用。你只需要写一次确认弹窗就能同时对接 Dify、Coze、自研 Agent 服务。我建议自研智能体平台的团队认真评估一下 AG-UI。自研平台最怕的就是每个功能都要从头造轮子尤其是交互层。你今天写了一个私有确认弹窗明天要接新的 LLM、新的 agent 框架交互层还得跟着改。用 AG-UI 把交互语义抽象出去后续扩展的边际成本会低很多。3. 接入 AG-UI 的实操路径3.1 最小接入方案一个“用户确认”交互上手 AG-UI 并不需要一下子引入完整体系。我建议从最小的场景开始实现一个“用户确认”交互。比如用户让智能体删除一份项目文件按下面五步走就能跑通整个链路在前端项目中引入 AG-UI Web SDK并建立 RTUI 通道。智能体在执行删除动作之前向运行时发送一个 confirm 类型的 Action。前端收到 Action渲染一个确认弹窗展示文件名、影响范围、操作风险。用户点击“确认删除”或“取消”。前端把结果回传给智能体智能体根据结果决定是否真正执行删除。这个流程看起来简单但它已经把 AG-UI 的核心机制都覆盖了Action 的发送、UI 渲染、用户反馈回传。跑通这一步之后再慢慢加 requestPermission、form、prompt 这些动作类型就有了一个可以持续演进的地基。可能有人会问确认一个删除操作而已写个 window.confirm 不就行了吗单机场景确实行。但你的智能体如果跑在云端用户操作在 Web 端Window.confirm 根本不具备跨端通信能力。AG-UI 的价值正在于把这种高频、跨端的交互做成标准化协议而不是每个项目重新发明一遍。3.2 关键消息结构与流程设计在动手写代码之前先把消息结构想清楚否则后面会踩很多坑。AG-UI 的 Action 大致长这样{ jsonrpc: 2.0, method: rtui/action, params: { actionId: act_9f3e7a2c, type: confirm, title: 确认删除文件, description: 文件 report_2024_final.pdf 将被永久删除此操作不可恢复。, confirmLabel: 删除, cancelLabel: 取消, timeout: 300000 } }这里有几个字段值得单独说明actionId 必须是全局唯一的。你可以用 UUID也可以自己生成带业务前缀的 ID但一定要保证在分布式环境下的唯一性。type 决定前端渲染哪种交互组件。我建议在前端做一个 Action 类型注册表每种类型对应一个 React/Vue 组件新增类型时不用改路由逻辑。timeout 一定要设置。用户可能去开会Action 挂在界面上很久智能体端不能一直无限等待。我通常给确认类动作设 5 分钟超市默认拒绝安全性优先。当用户做出操作后前端回传结果的逻辑大致是{ jsonrpc: 2.0, method: rtui/action_result, params: { actionId: act_9f3e7a2c, status: approved, data: { note: 用户确认删除 } } }status 字段我一般定义三种approved、declined、timeout。前端在超时前主动触发成功或失败回执超时后由智能体端自动按 declined 处理。这样整个消息流转就变得可靠且可审计。3.3 从前端到后端的完整链路下面给一个简化版的可运行示例。假设前端用 TypeScript React后端用 Node.js。代码我刻意写得精简目的是让你看清楚消息流动的方向而不是照抄包名就能跑。前端部分import { AGUIWebClient } from ag-ui/web; const client new AGUIWebClient({ url: wss://api.yoursite.com/rtui, autoReconnect: true }); client.on(rtui/action, async (action) { switch (action.type) { case confirm: return handleConfirm(action); case requestPermission: return handlePermission(action); default: throw new Error(Unsupported action type: ${action.type}); } }); async function handleConfirm(action) { const confirmed window.confirm( ${action.title}\n\n${action.description} ); return client.sendResult({ actionId: action.id, status: confirmed ? approved : declined }); }后端部分import { AGUIRuntime } from ag-ui/web; const runtime new AGUIRuntime({ wsServer: yourWebSocketServer }); // 智能体执行删除之前先发一个确认动作 const result await runtime.sendActionAndWait({ type: confirm, title: 确认删除文件, description: 文件 report_2024_final.pdf 将被永久删除此操作不可恢复。, confirmLabel: 删除, cancelLabel: 取消, timeout: 300000 }); if (result.status approved) { await deleteFile(report_2024_final.pdf); } else { await sendToast(用户已取消删除操作); }整个代码最重要的是理解“等待”的逻辑。智能体调用 sendActionAndWait 后会挂起当前任务直到前端回填了 actionId 对应的结果才会继续。这种设计天然适合异步交互你要做的只是保证 actionId 的关联正确。如果前端 SDK 的包名和 API 与官方不同不要慌重点还是概念链路。协议本身会演进但“智能体发动作 → 用户界面展示 → 用户反馈 → 智能体拿到结果”这个骨架不会变。4. 常见问题与踩坑记录4.1 协议选型与边界问题接入 AG-UI 的过程中最先遇到的坑其实是“什么时候该用”。很多团队犯的错是把所有交互都塞给 AG-UI结果把简单的流式输出也做成了 Action导致前端组件爆炸。我个人的判断标准很简单只有“人必须介入才能继续”的节点才需要 Action。比如模型在生成文本过程中用户不需要确认每个字符但智能体要访问外部系统、要删除数据、要用户提供关键参数时才需要发 Action。另一个常见困惑是 MCP 和 AG-UI 怎么选。实际上这两者不是一个赛道。MCP 解决“智能体如何调用工具”AG-UI 解决“智能体如何和用户打交道”。在同一个项目里完全可以让智能体通过 MCP 调用工具同时在关键节点通过 AG-UI 请求用户确认。二者是互补关系不是替代关系。4.2 实时链路与状态同步真正把 AG-UI 部署到线上第一个棘手的现实问题是 WebSocket 断线。用户正在看确认弹窗网络闪断智能体端不知道用户点了什么前端也不知道该把结果发到哪里。我遇到过几次类似场景排查下来的经验是未确认的 Action 必须要做本地持久化。具体做法是前端收到 Action 后先把 actionId、类型、标题、描述写进 localStorage 或 IndexedDB等 WebSocket 重连成功后再渲染弹窗。这样即使断线用户刷新页面后还能看到待确认的订单不至于无声消失。智能体端也一样超时之前没收到回执不要立即重试发同一个 Action先确认前一个 Action 是否已失效。再有一个多标签页问题用户在同一台电脑开了两个浏览器标签页同一个 Action 怎么处理我的做法是服务端把 actionId 绑定到 sessionId只让当前活跃的标签页消费动作其余标签页收到后直接忽略。实现上可以在前端用 BroadcastChannel 广播“当前已处理 actionId”避免重复弹窗。4.3 权限与安全确认不是走过场这是我最想强调的一个坑。AG-UI 只是协议它保证了用户能确认但并不能保证用户点击“允许”之后的操作是安全的。很多团队把确认按钮做得过于顺手用户习惯性点“确定”结果权限一放就收不回来。我在自己的项目里定了几条铁律权限最小化。每次敏感操作独立确认不要因为用户同意过一次读取 Excel就默认后续所有文件读取都被允许。审计闭环。每次 Action 的 actionId、用户操作、时间戳全部记录到日志出了问题能回溯到具体某一次点击。防误触。删除、转账、发布类操作确认框里要求用户输入目标对象的关键字而不是只点“确定”。比如删除文件前让用户在输入框里打一遍“report_2024_final.pdf”打对了才激活删除按钮。这种做法看起来多一步实际能把误操作概率降低一个量级。协议的标准化只能提供交互框架真正的安全边界还是由业务方一层层垒起来的。4.4 常见问题速查表问题常见原因解决方法Action 发出去前端没反应WebSocket 未连上 / Action 类型未注册检查连接状态注册所有 Action 类型对应的 UI 组件用户确认后智能体端超时回执 actionId 对不上 / 网络延迟检查 actionId 映射适当调大 timeout断线重连后重复弹窗未做 Action 幂等服务端记录 actionId 状态前端只处理未消费的动作用户长时间不操作任务卡死未设置 timeout所有 Action 必带 timeout超时默认拒绝同一动作多个标签页同时弹窗未绑定 sessionId服务端绑定 sessionId前端用 BroadcastChannel 去重权限确认通过后执行出错用户授权动作与业务执行未关联保证执行时二次校验权限不信任单个确认结果5. 对智能体开发生态的影响与扩展空间5.1 多智能体协作与消息路由AG-UI 的标准化还有个容易被低估的价值多智能体协作。当系统里有多个 Agent 在跑每个 Agent 都可能需要用户输入如果每个 Agent 各写一套 UI 交互前端根本没法维护。AG-UI 把“用户交互”统一成 Action 之后消息路由变得格外清晰主 Agent 负责发 Action 给用户副 Agent 处理完业务后把结果汇总给主 Agent需要用户确认时再统一弹窗。我之前接触过一个多 Agent 方案一个 Agent 管销售数据一个 Agent 管邮件发送。两个 Agent 要协作“给客户发周报”销售 Agent 生成数据邮件 Agent 准备正文最后由一个主 Agent 发起确认动作用户点了“发送”邮件 Agent 才真正执行。整个过程只出现一次确认弹窗体验非常顺滑。没有标准协议的话这个“统一弹窗”的需求会让前端开发崩溃。5.2 从网页到桌面客户端的演进目前 AG-UI 的多数实现聚焦在 Web 场景但桌面端和移动端的需求同样强烈。比如一个本地运行的知识库助手要读取你桌面上的 PDF 文件就需要系统级的文件访问权限确认。Web 端的确认弹窗在桌面应用里不一定适用桌面应用可能需要原生的权限申请对话框。我个人的判断是协议本身只要抽象得够底层跨端复用是水到渠成的事。RTUI 关心的是实时传输不关心宿主环境AG-UI Web 虽然名字里带 Web但组件渲染层可以替换成 React Native、Flutter 甚至原生控件。未来大概率会出现针对桌面端、移动端的 SDK 适配层到时候同一套 Action 语义可以横跨所有客户端。5.3 团队如果要入局建议从哪里切入如果你的团队现在想尝试 AG-UI我建议先挑一个非核心、只读场景的小功能试点。比如“智能体查询数据后用户确认后再导出 Excel”这种低风险动作把现有确认弹窗改成标准 Action跑通链路后再逐步扩大范围。具体建议有三点先把现有项目里所有涉及用户确认、授权、表单收集的代码梳理一遍看看哪些适合抽象成 Action。在实验环境打通 AG-UI Web RTUI 的最小链路确认第三方 SDK 的稳定性和可维护性。如果要做二次开发优先关注 Action 生命周期管理和超时重试机制这是生产环境最容易出问题的地方。千万不要一上来就大动干戈重构全平台。小步快跑拿一个真实场景验证价值比引入整套协议然后搁置更有意义。回到开头的问题智能体产品要真正让用户信任交互环节的标准化是绕不开的课题。MCP 让智能体有了更多的“手”AG-UI 则让智能体学会了在动手之前“问一问”。我个人在实际项目里的体会是引入 AG-UI 的第一步不是安装 SDK而是重新审视你产品里所有需要用户介入的节点——把这些节点抽象成标准动作后整个应用架构会清晰很多这次重构投入的时间完全值得。 
长河君 · 2026/9/9 16:31:13 · 阅读 1.2k AG-UI：补齐AI智能体与用户交互的标准化协议
1. 为什么需要一个“智能体与用户之间”的协议1.1 MCP 解决了一半问题另一半卡在“人的界面”从 2024 年底开始做 AI 智能体AI Agent开发的团队几乎绕不开一个词MCP。它把“工具”这件事标准化了智能体要读取 GitHub 仓库、搜索 Notion 文档、查数据库、调用第三方 API只要在 MCP Server 里注册一下任何支持 MCP 的客户端都能直接调。这个设计确实把“模型连接外部世界”的门槛大幅降低到现在基本成了事实上的业界标准。但真正把智能体推到业务前线的团队很快会撞到另一堵墙智能体要执行敏感操作时怎么跟用户打交道我举个很常见的例子员工让智能体“把这周的销售数据整理成周报并邮件发给各区域负责人”这条任务链路里至少有三个地方必须让人介入智能体要读取包含客户信息的 Excel 文件需要先获得授权汇总完成后用户要检查周报内容是否正确点击发送之前用户要确认收件人列表和邮件正文没有错漏。这些动作不能静默执行。用户至少要知情、确认有时候还要在中间补充参数。但目前的 MCP 协议里对话链路是“模型 → 智能体运行时 → 工具”整个过程几乎没有给“人”留下标准化的位置。你可以自己在代码里硬编码一个确认弹窗也可以在某个前端框架里写一个私有模态框但这些都属于项目里的“私货”换一个客户端、换一个前端框架就要全部重写。1.2 AG-UI 想解决的问题把“人在回路”标准化AG-UI 要补的正是这一块智能体与应用之间关于“用户交互”的部分。它不是一个模型协议也不是 agent 编排协议而是一套描述“智能体如何在用户界面上发起和回收交互动作”的开放协议。你可以简单理解为MCP 管“智能体调用世界”AG-UI 管“智能体调用用户”。打个比方。MCP 像物流系统把货物从仓库送到你楼下AG-UI 则管签收、开箱、让你检查货物是否符合预期。没有签收环节快递永远只是“看起来送到了”没有用户交互协议智能体也只是“看起来把活干完了”。如果智能体执行的是删除文件、转账、发邮件这种不可逆操作缺少一个标准化的“人参与确认”环节业务方根本不敢放它上线。这里要特别强调一点AG-UI 并非要取代 MCP也不和 LangChain、Dify、Coze 这类平台冲突。它作用在更靠近应用层的位置目标是把“AI 智能体与用户应用之间的交互方式”做成公共标准让不同团队不再重复造轮子。这个协议由 Braintrust 等团队推动目前已经有一些开源实现和 SDK正在逐步被智能体应用开发者采用。1.3 适合谁、用在什么场景如果你属于下面这几类人AG-UI 值得你花时间研究做智能体应用前后端开发的工程师。Chatbot、Agent 服务只要涉及“用户确认”或“中途收集信息”就需要一套可靠的交互机制。智能体平台研发团队。自建 Agent 平台或者对 Dify、Coze 做二次开发的人需要把用户授权、审批、确认的交互做成标准能力而不是每次改一个界面就返工。做 RPA、浏览器自动化、桌面端自动化产品的人。自动化流程执行到关键步骤时必须把控制权交还给用户AG-UI 正好覆盖这个环节。企业数据助手、内部知识库问答等需要权限审批的场景。员工让智能体读取核心系统数据之前必须经过用户点击授权这个动作如果走标准协议审计和合规都会轻松很多。我自己的感受是AG-UI 本质上是在解决一个“最后一公里”的问题。模型能力强不强是一回事智能体能不能被用户信任是另一回事。没有标准的交互确认层再强的 Agent 都只敢在沙箱里玩一到真实业务就露怯。2. AG-UI 的核心设计与组件拆解2.1 核心概念UI Action 与运行时AG-UI 最核心的抽象是 UI Action也就是“用户界面动作”。它把智能体想要从用户那里获得的反馈统一封装成动作。我在实际项目里用过比较高频的几种类型requestPermission请求权限。比如读取本地文件、访问某个网页、调用外部 API都需要先向用户申请。prompt向用户提问。智能体运行到一半发现缺必要参数比如生成周报时不确定要按哪个语言输出就直接发一个提问动作。form收集结构化表单。需要用户同时提供多个字段时比如“目标城市”和“期望出发时间”用表单一次收齐。confirm确认类动作。删除文件、发送邮件、提交订单这类高风险操作必须让用户明确二选一。notify通知。把结果或中间状态展示给用户不要求用户反馈。这些动作并不是分散的弹窗组件而是由一套运行时Runtime来统一分发和处理。智能体端把 Action 发给运行时运行时负责把它路由到正确的 UI 组件UI 组件完成用户交互后再把结果通过运行时返回给智能体。整个过程是异步的用户的思考时间完全不受智能体执行速度影响。我在设计自己的系统时把 Action 看成一种特殊的 JSON-RPC 消息。动作里必须带一个全局唯一的 actionId因为用户在 UI 上确认需要时间智能体端可能已经跑到了下一个节点回执必须能对齐到对应步骤。没有这个 id整个消息流转根本没法追踪。2.2 AG-UI Web 与 RTUI 的分工AG-UI 协议体系里有两个容易混淆的名词AG-UI Web 和 RTUI。它们的边界很清晰但不少刚接触的人会搞混。按我自己的理解可以这么划分AG-UI Web 是前端侧的 SDK 和界面渲染层。它关注的是“把 Action 渲染成什么 UI 元素”“用户操作后如何返回结果”。比如一个 confirm 动作在前端可以被渲染成普通弹窗也可以被渲染成侧边栏卡片这是 SDK 的灵活之处。RTUI 是实时传输层。它关注的是字节和连接如何建立 WebSocket 通道、如何处理断线重连、消息如何编解码。RTUI 不关心 UI 组件长什么样只关心消息能不能稳定地从智能体端到达前端。用一张表格来对比会更清楚维度MCPAG-UI WebRTUI解决核心问题智能体调用外部工具智能体与用户的界面交互交互消息的实时传输消息方向Server 与 Client 之间Agent - UI - User - UI - Agent双向实时消息典型消息tools/callrtui/actionws 帧 / SSE 事件主要使用者开发者与 Agent 运行时前端 SDK传输层实现简单说RTUI 是 AG-UI Web 的底层传输底座。两者可以分开使用也可以配合使用。如果你只想做一套标准的用户确认流程不关心底层是 WebSocket 还是 SSE那直接上手 AG-UI Web 就够了。如果你的智能体跑在云端需要在边缘节点和 Web 前端之间建立低延迟通道那就得在 RTUI 上花点功夫。2.3 与主流 Agent 平台Dify、Coze 等的配合关系Dify、Coze 这类智能体编排平台目前已经把 MCP 工具接入做得相当成熟能快捷地让 Agent 调用各种 API。但“执行到一半需要用户确认”这个能力各家平台的实现方式依然千差万别有的是 Workflow 里的“人工审核”节点有的是会话交互里的特殊消息类型有的是你自己写插件去调用前端 SDK。结果就是你在 Dify 上做的一套确认流程搬到 Coze 上基本要重写。AG-UI 的价值在这里就体现出来了。如果平台侧把“请求用户授权”“等待用户确认”“收集用户输入”这些能力统一按 AG-UI 的方式暴露那么上层应用和前端 UI 就可以跨平台复用。你只需要写一次确认弹窗就能同时对接 Dify、Coze、自研 Agent 服务。我建议自研智能体平台的团队认真评估一下 AG-UI。自研平台最怕的就是每个功能都要从头造轮子尤其是交互层。你今天写了一个私有确认弹窗明天要接新的 LLM、新的 agent 框架交互层还得跟着改。用 AG-UI 把交互语义抽象出去后续扩展的边际成本会低很多。3. 接入 AG-UI 的实操路径3.1 最小接入方案一个“用户确认”交互上手 AG-UI 并不需要一下子引入完整体系。我建议从最小的场景开始实现一个“用户确认”交互。比如用户让智能体删除一份项目文件按下面五步走就能跑通整个链路在前端项目中引入 AG-UI Web SDK并建立 RTUI 通道。智能体在执行删除动作之前向运行时发送一个 confirm 类型的 Action。前端收到 Action渲染一个确认弹窗展示文件名、影响范围、操作风险。用户点击“确认删除”或“取消”。前端把结果回传给智能体智能体根据结果决定是否真正执行删除。这个流程看起来简单但它已经把 AG-UI 的核心机制都覆盖了Action 的发送、UI 渲染、用户反馈回传。跑通这一步之后再慢慢加 requestPermission、form、prompt 这些动作类型就有了一个可以持续演进的地基。可能有人会问确认一个删除操作而已写个 window.confirm 不就行了吗单机场景确实行。但你的智能体如果跑在云端用户操作在 Web 端Window.confirm 根本不具备跨端通信能力。AG-UI 的价值正在于把这种高频、跨端的交互做成标准化协议而不是每个项目重新发明一遍。3.2 关键消息结构与流程设计在动手写代码之前先把消息结构想清楚否则后面会踩很多坑。AG-UI 的 Action 大致长这样{ jsonrpc: 2.0, method: rtui/action, params: { actionId: act_9f3e7a2c, type: confirm, title: 确认删除文件, description: 文件 report_2024_final.pdf 将被永久删除此操作不可恢复。, confirmLabel: 删除, cancelLabel: 取消, timeout: 300000 } }这里有几个字段值得单独说明actionId 必须是全局唯一的。你可以用 UUID也可以自己生成带业务前缀的 ID但一定要保证在分布式环境下的唯一性。type 决定前端渲染哪种交互组件。我建议在前端做一个 Action 类型注册表每种类型对应一个 React/Vue 组件新增类型时不用改路由逻辑。timeout 一定要设置。用户可能去开会Action 挂在界面上很久智能体端不能一直无限等待。我通常给确认类动作设 5 分钟超市默认拒绝安全性优先。当用户做出操作后前端回传结果的逻辑大致是{ jsonrpc: 2.0, method: rtui/action_result, params: { actionId: act_9f3e7a2c, status: approved, data: { note: 用户确认删除 } } }status 字段我一般定义三种approved、declined、timeout。前端在超时前主动触发成功或失败回执超时后由智能体端自动按 declined 处理。这样整个消息流转就变得可靠且可审计。3.3 从前端到后端的完整链路下面给一个简化版的可运行示例。假设前端用 TypeScript React后端用 Node.js。代码我刻意写得精简目的是让你看清楚消息流动的方向而不是照抄包名就能跑。前端部分import { AGUIWebClient } from ag-ui/web; const client new AGUIWebClient({ url: wss://api.yoursite.com/rtui, autoReconnect: true }); client.on(rtui/action, async (action) { switch (action.type) { case confirm: return handleConfirm(action); case requestPermission: return handlePermission(action); default: throw new Error(Unsupported action type: ${action.type}); } }); async function handleConfirm(action) { const confirmed window.confirm( ${action.title}\n\n${action.description} ); return client.sendResult({ actionId: action.id, status: confirmed ? approved : declined }); }后端部分import { AGUIRuntime } from ag-ui/web; const runtime new AGUIRuntime({ wsServer: yourWebSocketServer }); // 智能体执行删除之前先发一个确认动作 const result await runtime.sendActionAndWait({ type: confirm, title: 确认删除文件, description: 文件 report_2024_final.pdf 将被永久删除此操作不可恢复。, confirmLabel: 删除, cancelLabel: 取消, timeout: 300000 }); if (result.status approved) { await deleteFile(report_2024_final.pdf); } else { await sendToast(用户已取消删除操作); }整个代码最重要的是理解“等待”的逻辑。智能体调用 sendActionAndWait 后会挂起当前任务直到前端回填了 actionId 对应的结果才会继续。这种设计天然适合异步交互你要做的只是保证 actionId 的关联正确。如果前端 SDK 的包名和 API 与官方不同不要慌重点还是概念链路。协议本身会演进但“智能体发动作 → 用户界面展示 → 用户反馈 → 智能体拿到结果”这个骨架不会变。4. 常见问题与踩坑记录4.1 协议选型与边界问题接入 AG-UI 的过程中最先遇到的坑其实是“什么时候该用”。很多团队犯的错是把所有交互都塞给 AG-UI结果把简单的流式输出也做成了 Action导致前端组件爆炸。我个人的判断标准很简单只有“人必须介入才能继续”的节点才需要 Action。比如模型在生成文本过程中用户不需要确认每个字符但智能体要访问外部系统、要删除数据、要用户提供关键参数时才需要发 Action。另一个常见困惑是 MCP 和 AG-UI 怎么选。实际上这两者不是一个赛道。MCP 解决“智能体如何调用工具”AG-UI 解决“智能体如何和用户打交道”。在同一个项目里完全可以让智能体通过 MCP 调用工具同时在关键节点通过 AG-UI 请求用户确认。二者是互补关系不是替代关系。4.2 实时链路与状态同步真正把 AG-UI 部署到线上第一个棘手的现实问题是 WebSocket 断线。用户正在看确认弹窗网络闪断智能体端不知道用户点了什么前端也不知道该把结果发到哪里。我遇到过几次类似场景排查下来的经验是未确认的 Action 必须要做本地持久化。具体做法是前端收到 Action 后先把 actionId、类型、标题、描述写进 localStorage 或 IndexedDB等 WebSocket 重连成功后再渲染弹窗。这样即使断线用户刷新页面后还能看到待确认的订单不至于无声消失。智能体端也一样超时之前没收到回执不要立即重试发同一个 Action先确认前一个 Action 是否已失效。再有一个多标签页问题用户在同一台电脑开了两个浏览器标签页同一个 Action 怎么处理我的做法是服务端把 actionId 绑定到 sessionId只让当前活跃的标签页消费动作其余标签页收到后直接忽略。实现上可以在前端用 BroadcastChannel 广播“当前已处理 actionId”避免重复弹窗。4.3 权限与安全确认不是走过场这是我最想强调的一个坑。AG-UI 只是协议它保证了用户能确认但并不能保证用户点击“允许”之后的操作是安全的。很多团队把确认按钮做得过于顺手用户习惯性点“确定”结果权限一放就收不回来。我在自己的项目里定了几条铁律权限最小化。每次敏感操作独立确认不要因为用户同意过一次读取 Excel就默认后续所有文件读取都被允许。审计闭环。每次 Action 的 actionId、用户操作、时间戳全部记录到日志出了问题能回溯到具体某一次点击。防误触。删除、转账、发布类操作确认框里要求用户输入目标对象的关键字而不是只点“确定”。比如删除文件前让用户在输入框里打一遍“report_2024_final.pdf”打对了才激活删除按钮。这种做法看起来多一步实际能把误操作概率降低一个量级。协议的标准化只能提供交互框架真正的安全边界还是由业务方一层层垒起来的。4.4 常见问题速查表问题常见原因解决方法Action 发出去前端没反应WebSocket 未连上 / Action 类型未注册检查连接状态注册所有 Action 类型对应的 UI 组件用户确认后智能体端超时回执 actionId 对不上 / 网络延迟检查 actionId 映射适当调大 timeout断线重连后重复弹窗未做 Action 幂等服务端记录 actionId 状态前端只处理未消费的动作用户长时间不操作任务卡死未设置 timeout所有 Action 必带 timeout超时默认拒绝同一动作多个标签页同时弹窗未绑定 sessionId服务端绑定 sessionId前端用 BroadcastChannel 去重权限确认通过后执行出错用户授权动作与业务执行未关联保证执行时二次校验权限不信任单个确认结果5. 对智能体开发生态的影响与扩展空间5.1 多智能体协作与消息路由AG-UI 的标准化还有个容易被低估的价值多智能体协作。当系统里有多个 Agent 在跑每个 Agent 都可能需要用户输入如果每个 Agent 各写一套 UI 交互前端根本没法维护。AG-UI 把“用户交互”统一成 Action 之后消息路由变得格外清晰主 Agent 负责发 Action 给用户副 Agent 处理完业务后把结果汇总给主 Agent需要用户确认时再统一弹窗。我之前接触过一个多 Agent 方案一个 Agent 管销售数据一个 Agent 管邮件发送。两个 Agent 要协作“给客户发周报”销售 Agent 生成数据邮件 Agent 准备正文最后由一个主 Agent 发起确认动作用户点了“发送”邮件 Agent 才真正执行。整个过程只出现一次确认弹窗体验非常顺滑。没有标准协议的话这个“统一弹窗”的需求会让前端开发崩溃。5.2 从网页到桌面客户端的演进目前 AG-UI 的多数实现聚焦在 Web 场景但桌面端和移动端的需求同样强烈。比如一个本地运行的知识库助手要读取你桌面上的 PDF 文件就需要系统级的文件访问权限确认。Web 端的确认弹窗在桌面应用里不一定适用桌面应用可能需要原生的权限申请对话框。我个人的判断是协议本身只要抽象得够底层跨端复用是水到渠成的事。RTUI 关心的是实时传输不关心宿主环境AG-UI Web 虽然名字里带 Web但组件渲染层可以替换成 React Native、Flutter 甚至原生控件。未来大概率会出现针对桌面端、移动端的 SDK 适配层到时候同一套 Action 语义可以横跨所有客户端。5.3 团队如果要入局建议从哪里切入如果你的团队现在想尝试 AG-UI我建议先挑一个非核心、只读场景的小功能试点。比如“智能体查询数据后用户确认后再导出 Excel”这种低风险动作把现有确认弹窗改成标准 Action跑通链路后再逐步扩大范围。具体建议有三点先把现有项目里所有涉及用户确认、授权、表单收集的代码梳理一遍看看哪些适合抽象成 Action。在实验环境打通 AG-UI Web RTUI 的最小链路确认第三方 SDK 的稳定性和可维护性。如果要做二次开发优先关注 Action 生命周期管理和超时重试机制这是生产环境最容易出问题的地方。千万不要一上来就大动干戈重构全平台。小步快跑拿一个真实场景验证价值比引入整套协议然后搁置更有意义。回到开头的问题智能体产品要真正让用户信任交互环节的标准化是绕不开的课题。MCP 让智能体有了更多的“手”AG-UI 则让智能体学会了在动手之前“问一问”。我个人在实际项目里的体会是引入 AG-UI 的第一步不是安装 SDK而是重新审视你产品里所有需要用户介入的节点——把这些节点抽象成标准动作后整个应用架构会清晰很多这次重构投入的时间完全值得。