AG-UI 在 IoT 控制台里怎么落地：设备状态、命令确认与人机协同

AG-UI 落到 IoT 控制台时，最重要的不是让 Agent 在页面上“会聊天”，而是让设备状态、建议动作、命令确认、执行结果和失败回滚都能被用户看见和打断。如果一个 IoT 控制台只把 AG-UI 当作聊天消息流，Agent 可能会解释得很好，但真正危险的设备动作仍然缺少状态边界、人工确认和审计证据。

本文的核心结论是：AG-UI 适合承担 IoT 控制台的人机交互层，MCP 或平台 API 适合承担工具与数据边界，Function Calling 只应该生成受控动作请求。 在工程实现上，AG-UI 应该围绕五个对象设计：设备状态、Agent 任务状态、命令草案、人工确认、审计事件。

决策块

如果一个 IoT Agent 只能查询设备状态和生成建议，AG-UI 可以先用于状态流、证据展示和人工确认卡片。只有当命令链路已经具备权限校验、幂等键、超时处理、回滚策略和审计日志时，才应该把 AG-UI 扩展到真实命令执行体验。否则，AG-UI 会让交互更顺，但不会让控制链路更安全。

1. 不要把 AG-UI 放在设备控制链路里

AG-UI 官方文档把它描述为连接 AI Agent 与用户应用的事件型协议，重点包括 streaming events、state management、messages、tool-call lifecycle 和 human-in-the-loop 交互。这个定位很关键：AG-UI 解决的是“用户界面如何跟上 Agent 的状态”，不是“设备命令如何被授权、下发和确认”。

在 IoT 控制台里，安全的分层通常应该是这样：

这个表的实际含义是：AG-UI 可以让操作员看清 Agent 正在做什么，但不能替代 IoT 平台的命令治理。 对温控、门禁、工业设备、能源设备这类有现场风险的对象，任何“Agent 说可以执行，所以就直接执行”的设计都不应该进入生产。

2. 五个事件对象比一条聊天流更重要

IoT 控制台的 Agent 交互通常不是单纯问答，而是一段可观察的任务过程。建议从下面五个事件对象开始设计 AG-UI 事件，而不是先做一个漂亮的聊天框。

AG-UI 的价值在这里变得明确：它把 Agent 的中间过程变成前端可渲染、可中断、可恢复的事件序列。对用户来说，界面不再只是等一个最终回答，而是能看到 Agent 已经查了哪些设备、引用了哪些告警、准备下发什么命令，以及为什么需要人工确认。

3. 推荐的交互状态机

下面这张图只表达一个问题：IoT 控制台里的 Agent 命令建议应该如何从分析走到确认、执行和回滚。

flowchart TD

A("用户提出运维问题"):::slate --> B("读取设备状态与历史遥测"):::blue
B --> C("Agent 形成诊断与证据"):::cyan
C --> D("生成命令草案"):::orange
D --> E{"是否高风险"}:::violet
E -->|否| F("低风险动作进入后端校验"):::green
E -->|是| G("显示人工确认卡片"):::orange
G --> H{"用户确认"}:::violet
H -->|拒绝或超时| I("取消并记录审计"):::slate
H -->|确认| F
F --> J("命令状态机执行"):::blue
J --> K{"ACK / 超时 / 失败"}:::violet
K -->|ACK| L("更新状态与审计日志"):::green
K -->|超时或失败| M("提示回滚或创建工单"):::orange

classDef blue fill:#EAF4FF,stroke:#3B82F6,color:#16324F,stroke-width:2px;
classDef cyan fill:#E9FBF8,stroke:#14B8A6,color:#134E4A,stroke-width:2px;
classDef orange fill:#FFF3E8,stroke:#F08A24,color:#7C3F00,stroke-width:2px;
classDef violet fill:#F4EDFF,stroke:#8B5CF6,color:#4C1D95,stroke-width:2px;
classDef green fill:#ECFDF3,stroke:#22C55E,color:#14532D,stroke-width:2px;
classDef slate fill:#F8FAFC,stroke:#64748B,color:#1F2937,stroke-width:2px;

这张图背后的判断是：AG-UI 负责把“等待确认、执行中、失败、回滚建议”这些状态及时传给前端；真正的命令状态机仍然应该在后端控制平面里运行。 如果状态机放在前端或模型里，页面刷新、网络中断、重复点击和并发会让命令链路失去确定性。

4. 命令确认卡片应该显示哪些字段

命令确认是 AG-UI 在 IoT 控制台中最有价值的界面模式之一。它不应该只是一个“同意 / 拒绝”按钮，而应该把动作风险和后端约束讲清楚。

一个可生产使用的确认卡片至少应包含：

• device_id、设备名称、站点或空间位置。
• 当前状态、目标状态和数据时间戳。
• 命令类型、参数、单位、允许范围。
• 影响范围，例如单设备、设备组、场景或自动化规则。
• 风险等级和为什么需要确认。
• 幂等键、过期时间和重复提交处理方式。
• 预期 ACK、超时阈值和失败后的回滚或工单路径。
• 确认人、权限角色和审计记录。

这不是界面文案的细节，而是系统边界。如果确认卡片没有展示目标设备、参数、过期时间和失败路径，用户确认的其实不是一个可审计命令，而是一段模糊的自然语言建议。

5. 后端事件要比前端组件更稳定

很多团队会从 React 组件开始设计 Agent 控制台，但更可靠的做法是先固定事件模型。组件可以换，事件契约不能随便变。

推荐把 Agent 交互事件拆成四组：

AG-UI 的 event-based 架构适合承载这些交互事件，但事件内容应当来自后端事实源。模型可以提出诊断和命令草案，不能自己宣称设备已执行成功。设备是否执行成功，必须来自控制平面的 ACK、遥测回读或网关状态。

6. 与 MCP 和 Function Calling 怎么配合

AG-UI、MCP 和 Function Calling 可以组合成一个清晰的路径：

1. 用户在 AG-UI 界面发起问题，例如“为什么 3 号冷库温度一直偏高？”
2. Agent runtime 通过 MCP 或平台 API 调用工具，读取设备状态、历史遥测、告警和工单。
3. 模型使用 Function Calling 生成结构化的 propose_command 请求，而不是直接执行命令。
4. 后端控制平面校验权限、租户、设备状态、参数范围和风险等级。
5. AG-UI 向前端流出诊断证据、命令草案和人工确认事件。
6. 用户确认后，后端命令状态机执行并返回 ACK、失败或回滚建议。
7. AG-UI 把最终状态和审计结果展示给用户。

这里的关键边界是：Function Calling 只生成请求，MCP 或平台 API 只暴露受控工具，AG-UI 只呈现交互状态，IoT 控制平面才拥有最终执行权。

7. 什么时候不适合上 AG-UI

AG-UI 不应该被当作所有 IoT 控制台的默认答案。下面几种情况，先补基础能力比先做 Agent UI 更重要：

• 设备状态本身不可信，平台无法区分实时值、缓存值和过期值。
• 命令链路没有幂等键，重复点击或重试会导致重复执行。
• 没有按租户、站点、设备组和角色做权限隔离。
• 高风险动作没有人工确认和审计记录。
• 告警、工单、设备状态之间没有稳定的数据关联。
• 运维团队还不能接受 Agent 参与生产动作，只希望做只读问答。

在这些条件下，AG-UI 仍然可以用于只读诊断体验，但不应该接入真实控制命令。AG-UI 能改善人机协同体验，但不能弥补设备状态、命令可靠性和权限治理的缺口。

8. 落地检查清单

上线前建议至少检查下面 10 件事：

1. 是否明确区分只读诊断、低风险动作和高风险命令。
2. 每个命令是否有 command_id 和幂等键。
3. 每个确认动作是否记录用户、时间、设备、参数和风险等级。
4. 前端是否能展示 Agent 正在查询哪些事实源。
5. 用户是否能取消、拒绝、重试或升级为人工工单。
6. 命令失败是否有清楚的超时、失败和回滚路径。
7. AG-UI 事件是否只反映后端事实，而不是模型猜测。
8. MCP 或工具 API 是否做了租户、角色和资源范围限制。
9. Function Calling 的参数是否经过 schema、范围和业务规则校验。
10. 审计日志是否能串起用户请求、Agent 建议、人工确认、命令执行和设备回读。

9. 结论

AG-UI 在 IoT 控制台里的正确位置，是 Agent 与操作员之间的交互协议层。它让 Agent 的分析、证据、状态、命令草案和确认过程变得可见，也让用户能够中断、确认或拒绝高风险动作。

但 AG-UI 不应该拥有设备控制权。生产级 IoT 控制台仍然需要后端命令状态机、权限治理、幂等、ACK、超时、回滚和审计。当 AG-UI 只负责交互可见性，MCP 或平台 API 负责工具边界，Function Calling 负责结构化动作请求，IoT 控制平面负责最终执行时，Agent 才适合进入真实运维控制台。

参考资料

• AG-UI Overview
• AG-UI Events
• AG-UI Architecture
• Model Context Protocol Specification
• OpenAI Function Calling Guide

FAQ

AG-UI 能不能直接下发 IoT 设备命令？

不建议。AG-UI 可以呈现命令草案、确认卡片和执行状态，但设备命令应该由后端控制平面执行。否则权限、幂等、审计和失败回滚都很难稳定。

AG-UI 和 MCP 在 IoT 控制台里有什么区别？

AG-UI 主要解决 Agent 与用户界面之间的事件和状态同步；MCP 主要解决 Agent 应用与外部工具、资源、提示上下文之间的连接边界。在 IoT 控制台里，AG-UI 面向操作员体验，MCP 面向工具和数据接入。

Function Calling 已经能调用函数，为什么还需要 AG-UI？

Function Calling 让模型产生结构化函数请求，但不定义前端如何展示分析过程、用户如何确认命令、如何中断任务、如何显示失败和回滚。AG-UI 解决的是这些交互状态的可见性问题。