做智能体应用最容易被低估的问题往往不是模型能力也不是工具调用链路而是“用户和智能体之间怎么对话”。上篇把AG-UI出现的原因和整体定位理了一遍今天这篇直接碰协议的核心机制消息类型、消息信封以及我认为整套协议里最值得抄走的那个设计——消息枚举环绕。如果你是正在做智能体产品、想把用户交互真正规范化的开发者这篇应该能帮你省下不少翻文档和踩坑的功夫。先给个一句话概括AG-UI做的是把“智能体对用户的一次表达”抽象成标准消息类型把“用户对智能体的回应”抽象成标准反馈消息让界面通信从“提示词里夹带的说辞”变成“结构化的API调用”。1. 为什么用户和智能体之间的对话也需要一份协议1.1 自然语言界面恰恰是最后一块没有标准的接口做后端的都认识OpenAPI做工具调用的都认识MCP数据库有SQL前端有组件库。但“agent和用户之间的对话”长期处于一种原始状态——哪个大模型上什么规则交互方式就是什么样子。这带来的后果很直接。用户在产品A里学会的智能体交互方式换到产品B里完全失效。同一个智能体接到不同渠道比如Web端、企业IM、移动端渲染逻辑和交互语义各自为政。更麻烦的是你没办法对这段对话做结构化的测试和审计因为“用户说了什么、智能体回了什么”在代码里只是一串自然语言历史记录。我见过不少团队在这个阶段会做的事拼命调prompt让模型“在回复里带个编号”“请用户选择A/B/C”。这能解决一部分问题但治标不治本。只要编号的生成、引用、失效规则没有被协议化它就随时会在多轮对话里崩掉。AG-UI要补的正是这个位置。它把交互语义从“模型临场发挥”变成“协议规定动作”。1.2 协议管语义不管样式这里有个容易被误解的点AG-UI不是一套UI组件库它不关心气泡长什么样、按钮颜色是什么。它约束的是“这条消息是什么性质、用户应当如何回应”而不是“这条消息长什么样”。怎么理解底层消息一旦标准化Web端可以把advice消息渲染成带按钮的卡片IM端可以渲染成带编号的文本列表语音端可以直接把它朗读出来。不同的端侧自行决定表现层但底层结构大家是同一个。这个设计非常关键。如果协议把UI样式也规定死它就不可能在不同终端和不同产品里推广。做协议的人很清楚样式是最容易变、最不该被约束的部分。语义才是各个终端都需要遵守的契约。1.3 一个典型问题场景举个我在落地时遇到的实例。用户告诉智能体“帮我订周二下午去深圳北的高铁。”智能体返回了三个候选班次。然后用户说“把出发时间改成傍晚的。”如果没有协议智能体需要从历史消息里凭语义去推断“傍晚”对应的是哪一个班次。模型推理能力再强这也是一个概率事件。它可能把“傍晚”理解成“下午六点左右”然后把三个候选班次里那个18:05的挑出来——但如果用户指的根本是另一个18:40的区间呢有协议之后一切变得简单智能体在返回候选班次时给每条消息带上编号。用户只需要回复“改成3号那种的”系统直接从协议层锁定3号消息完全不依赖模型对“傍晚”这个词的模糊语义推断。这就是AG-UI的实际价值。它不是给模型用的是给整个应用系统用来消除歧义的。2. 核心消息类型agent发给用户的每条消息都要“贴标签”2.1 消息类型整体清单AG-UI把智能体对用户的表达归纳成有限的几种消息类型。我实际使用中维护的核心清单如下消息类型语义典型场景用户响应方式notification单向告知无需回应“任务已完成”“系统将在5分钟后重启”无advice建议项用户可选“我推荐这三家餐厅您选一家”接受/拒绝/选择其中一项permission_request敏感操作前的授权请求“即将发送邮件是否允许”批准/拒绝input_request向用户征集结构化输入“请输入您的收货地址”填表/提供信息error出错与恢复引导“接口调用失败是否重试”重试/撤销/反馈这里是按我落地时整理的语义来划分的。AG-UI规范本身也会有一些字段和枚举定义不同版本可能存在差异。如果你要把代码写死一定以你接入版本的最新规范为准。2.2 语义边界为什么要分这么清我在早期版本里吃过一个亏把“建议”当“通知”发。当时智能体给用户返回了几个方案后用户完全不知道哪些是可选的、哪些只是告知。前端渲染时也不知道该给这条消息配什么操作入口。结果用户要么不知道怎么继续要么干脆把通知当成废话忽略掉。语义边界一旦在协议层清晰前端组件就能做出差异化的交互。advice消息可以渲染“接受/拒绝”按钮notification消息只读不可操作permission_request消息必须带明显的安全提示。用户体验的提升是即时的而且你不需要给每种终端写死交互逻辑端侧只需要识别消息类型自己决定怎么渲染。2.3 消息信封让异构消息有统一外壳不同类型消息的payload千差万别但它们在外面得套一个统一的外壳方便系统做路由、记录、超时处理。这个外壳就是消息信封。我在MAF里用的信封结构大致是这样{ messageId: msg_83921, messageType: advice, timestamp: 2025-06-20T10:30:00.000Z, allowInterrupt: true, context: { sessionId: session_1024, relatedSkill: booking_ticket }, payload: { content: 为您找到3个班次请选择, options: [ { id: opt_1, label: 14:30 出发 }, { id: opt_2, label: 17:05 出发 }, { id: opt_3, label: 18:40 出发 } ] } }各字段的作用messageId全局唯一后续引用、审计都靠它。messageType这条消息的语义标签。allowInterrupt用户是否允许打断当前流程。这个字段在长任务执行中特别重要没有它用户说“等一下”的时候agent很可能完全不理。context会话ID、关联技能等路由信息。payload具体内容类型之间差异很大。为什么信封这么重要因为一旦所有消息都套同一个外壳你就可以在系统层面做统一的消息路由、超时管理、日志审计。比如用户长时间没回应advice是重新询问还是默认跳过都能在路由层面统一处理。3. 消息枚举环绕解决“用户到底指哪条”的老大难问题3.1 问题的本质自然语言引用是概率性的先说一个我自己的亲身体会。用大模型做多轮对话最痛苦的不是模型答错而是模型“猜错了用户指的是哪条消息”。用户说“第一条不行”模型需要推断“第一条”是哪个历史消息。即便当前上下文里很清楚模型推断正确率可能高达95%但一旦进入关键操作比如改签、付款、删数据那5%的错误就是事故级的。AG-UI对这个问题给出的答案是消息枚举环绕。这个名字听起来唬人本质一句话用数字编号代替模糊指代把“引用某条消息”从概率推理变成确定性的协议动作。3.2 枚举环绕的工作过程整个机制的实际运转是这样agent生成一批候选消息时协议会给它们分配连续的编号。agent在自己的上下文约束里声明当前可响应的编号范围。用户端UI展示消息时同时展示编号。用户回复编号协议层直接锁定对应消息不再做语义推断。到第4步模型根本不需要“理解”用户指的是哪条消息编号直接决定了操作对象。歧义在这个设计里被物理性消除了。上下文约束的长相大概是这样的当前可响应的用户消息范围: [3, 4, 5] 规则: - 用户可以通过编号引用任意一条消息 - 你可以且只可以针对编号范围内的消息继续处理 - 编号范围之外的旧消息不得再作为操作对象 - 如果用户引用了范围外的编号请提示其重新选择这段约束会由MAF在每轮对话开始时自动注入系统提示并在消息范围变化时重新生成。3.3 和纯prompt工程的区别在哪里有人可能会说这玩意儿我用prompt也能实现——“请用户回复编号”。对单条消息内它能生效。我自己在早期就是靠prompt约束来做的一开始看起来跑得通。但一旦中间插入了工具返回、状态变更、用户切换话题、甚至模型自己引用了旧消息prompt里的编号规则就名存实亡了。协议层约束和提示词约束的根本区别在于执行位置。prompt约束依赖模型“记得”这个规则而协议约束是由外部系统在每轮对话中强制注入和维护的。模型无状态但协议有状态。这才是枚举环绕比“告诉模型你要编号”可靠得多的原因。我在落地过程中还发现一个细节编号在上下文被截断后需要重新生成。如果你训练的上下文管理逻辑把某些历史消息挤出了窗口而编号还在用户就会引用到模型已经看不到的消息。这个问题要在上下文管理模块里专门处理等会儿在坑的部分细说。4. 权限请求安全与流畅之间的平衡点4.1 一条完整的授权链路智能体一旦涉及真实操作比如发送邮件、删除数据、下单支付、修改配置就必须有权限请求这一环。AG-UI里对应的是permission_request消息。完整链路是这样的agent在执行敏感操作前生成permission_request消息。消息经由MAF路由到用户端。用户端展示操作摘要和安全提示附“允许/拒绝”按钮。用户做出选择。MAF把授权结果返回agentagent据此继续或中止。我判断“什么操作需要走权限请求”有个四象限清单满足任一条就走破坏性删除、覆盖、清空不可逆发出去就收不回的比如邮件、消息、转账涉及金钱任何与支付、扣费相关的涉及隐私数据读取或传输用户个人信息不给权限请求的粗糙做法是“让大模型自己判断要不要执行”。这在demo里没毛病但对真实用户的产品来说极其危险。模型既不知道操作的真实后果也没有被训练成安全边界负责人。安全判断的逻辑必须在协议层做不能交给模型的临场发挥。4.2 减少打断感的几种策略权限请求做多了之后我很快发现另一个问题每次都弹授权框用户烦不烦答案是真烦。尤其是任务执行到一半连续触发几次权限请求用户基本会失去耐心。所以我在MAF中做了三个降噪策略第一种是批量授权。同一个会话内agent连续执行多个同类操作时只请求一次权限。比如“我要批量归档100封邮件”一次授权覆盖整个批处理而不是每封邮件弹一次窗。第二种是会话临时授权。用户在某次会话中同意某个操作的权限后操作有效期持续到会话结束。比如用户授权“允许读取本周日志”在会话结束前不再重复询问。第三种是条件授权。用户可以在首次授权时附带条件比如“仅在测试模式下允许发送测试邮件”。这类条件授权很适合企业内部工具效率和安全兼顾。4.3 授权后的上下文沉淀授权结束不等于事情结束。我在实际项目中养成了一个习惯每次授权都要把结果写入会话上下文。原因很简单如果授权不写入上下文agent在接下来的几轮对话里可能忘了“用户已经允许过”于是再次发起permission_request。这不仅打断体验还会让用户觉得“这东西没记性”。授权记录里至少要有谁授权的、授予了什么操作、覆盖范围是什么、何时到期。这既是行为审计的基础也是后续自动决策的依据。AG-UI虽然定义了消息类型但授权状态的维护属于应用框架侧的逻辑MAF在这里要承担一部分状态管理职责。一个特别有用的实践是授权通过后在上下文约束里追加一行“当前会话已获得以下权限除非用户主动撤销否则不再重复请求”同时把撤销指令也接入对话语义。用户在任何时候说“以后不要再自动发邮件了”agent就能立刻理解并修改授权状态。5. 在MAF里落地AG-UI接入重点与几个典型的坑5.1 接入的四个关键步骤如果你也想在自己的框架里接AG-UI我的经验是分四步走。第一步是消息语义映射。把agent内部产生的各类输出分类映射到AG-UI的消息类型。这一步的本质是把“agent想做什么”翻译成“协议能表达什么”。我做的第一版映射表大约二十行覆盖通知、建议、权限请求、输入请求和错误处理。第二步是消息路由。信封出来之后所有消息走统一的消息总线而不是让每个技能模块自己调用发送接口。统一的入口才能做日志、审计、超时管理和权限校验。否则消息满天飞出了问题你根本没地方查。第三步是前端渲染适配。Web端和IM端各自解析信封按消息类型渲染。Web端可以按钮化操作IM端则通过编号交互或快捷回复。两端共用同一份消息结构只是皮肤不同。第四步是上下文约束注入。MAF在每轮对话开始时把当前“可响应范围”注入系统提示并在消息枚举变化时重新生成。这是把协议从“文档”变成“运行时”的关键一环。这四步的先后顺序我换过几次最后发现最好用的还是这个顺序先弄清楚有哪些消息再让消息流动起来然后渲染最后约束模型行为。5.2 踩过的坑把消息发出去之后的连锁问题第一个坑把notification当conversation用。当时有个技能模块直接往会话里塞了一条“已完成”文本用户想追问却没有任何入口。因为notification语义是不需要回应的前端也就不渲染任何操作按钮。后来我严格规定需要用户回应的场景一律用advice或input_requestnotification只用于纯告知。第二个坑编号范围没有随上下文截断重排。模型上下文窗口有限当旧消息被挤出窗口时如果编号没跟着变用户可能引用一个模型已经看不到的编号。我们最后在上下文管理模块里加了一个步骤每次截断后重新枚举当前可见消息并同步更新约束声明。第三个坑permission_request被模型当成普通消息“自我授权”。这个问题最隐蔽。当时模型在工具调用结果里看到“发送成功”之类的文本就误以为权限请求被批准了。根因是权限请求走的内容通道和通知一样模型自己看到了。修复方式是把permission_request消息放到单独的消息通道同时模型侧强制“未收到协议级授权成功事件前不得执行受保护操作”。第四个坑中断语义缺失。用户明确说“等一下”agent还在自顾自地继续执行工具调用场面一度非常尴尬。后来我在信封里固定启用allowInterrupt字段并且让MAF在识别到用户的中断意图后主动暂停当前任务序列而不是等着模型自己发现。5.3 一个值得提前考虑的设计AG-UI的接入不只是在代码里跑通一种协议它更是一种架构约束。你用不用它的判定标准不是“消息类型对不对”而是“系统是否能稳定地知道用户指的哪条消息、是否在敏感操作前可靠地停下来”。我个人是这么看的协议层解决的问题永远不要丢给提示词去解决。提示词是概率性的协议是确定性的。凡是能用协议表达的交互语义就一定要用协议表达。如果你也在搭智能体应用建议从今天起就把用户交互当成一份需要版本管理的接口契约来看待而不是让模型自由发挥。等到多终端、多模型跑起来的那一天你会感谢当初多花的这半天时间。下一篇我会把input_request的完整状态机拆开包括输入校验、中途修改、超时处理的流转细节。这块内容比较细但真的很值得做透。
