Agent UI 框架架构：跨平台设计模式与 AGenUI 深度解析

Agent UI 框架（Agent User Interface Framework）是专为 AI Agent 设计的用户界面构建工具集，它解决的核心问题是：当 AI Agent 具备自主操作能力时，如何为用户提供可控、可观测、可干预的交互界面。

2026 年之前，AI 的交互界面主要是聊天窗口——用户输入文本，AI 返回文本。这种对话框模式（Chat Interface）是 LLM 时代的默认交互范式，但它存在三个根本性局限：

第一，操作缺乏透明度。当 Agent 执行复杂任务（如"帮我预订下周去上海的机票和酒店"）时，用户只能看到一个加载动画或进度文字，无法实时了解 Agent 正在做什么、做了什么、遇到了什么问题。

第二，干预能力有限。如果 Agent 在任务执行过程中需要做决策（比如"航班 A 比航班 B 贵 200 元但时间更好"），用户无法在 Agent 操作的同时实时介入——只能等 Agent 完成后，再要求它重新执行。

第三，跨平台体验割裂。同一个 Agent 在手机、平板、电脑、智能手表上需要完全不同的界面适配。如果没有统一的 UI 框架，开发者必须为每个平台独立开发界面——工作量成倍增长，体验难以一致。

Agent UI 框架正是为了解决这些问题而诞生的。它提供了标准化的组件、状态管理方案和跨平台适配层，让开发者能够高效构建可观测、可控制、跨平台的 Agent 交互界面。

2026 年 5 月，高德（Amap/阿里巴巴旗下）开源了 AGenUI 框架——这是全球首个覆盖 iOS、Android、HarmonyOS 三端的 Agent UI 框架。AGenUI 的发布标志着 Agent UI 从"实验性探索"进入了"工业级标准"阶段。

为什么 Agent UI 成为新战场？ 因为 AI Agent 正在从"聊天工具"变为操作系统级应用。当 Agent 需要深度集成到用户的日常操作中——管理日程、处理邮件、控制智能家居、协调工作流——它需要的不再是一个简单的对话框，而是一套完整的交互体系。

构建 Agent UI 与设计传统应用界面有一个本质区别：传统应用的操作流程是确定性的——用户点击按钮 A，触发功能 B，界面跳转到页面 C。而 Agent 的操作流程是非确定性的——同一个指令，Agent 可能选择不同的执行路径，遇到不同的中间状态，产生不同的结果。

这种不确定性对 UI 设计提出了独特要求。业界逐渐形成了 Agent UI 的五大核心设计原则：

原则一：可观测性优先（Observability First）

Agent 执行的每一步都应该在界面上实时可见。这包括：当前正在执行的操作、已完成的步骤、待执行的步骤、遇到的错误和警告。用户不应该猜测 Agent 在做什么——界面应该主动告知。

实现方式通常包括：步骤时间线（Timeline）、实时日志流（Log Stream）、状态指示器（Status Indicator）。高德 AGenUI 提供了内置的 StepTracker 组件，自动将 Agent 的操作序列渲染为可视化的步骤进度条。

原则二：可干预性（Intervene-ability）

Agent 在执行过程中，用户应该能够随时介入。这包括：暂停当前操作、修改正在进行的任务、撤销已完成的步骤、提供额外信息引导 Agent 的决策。

可干预性要求 Agent UI 具备双向通信能力——不仅 Agent 可以向用户展示信息，用户也可以随时向 Agent 发送指令。这与传统应用的"请求-响应"模式完全不同。

原则三：权限透明（Permission Transparency）

Agent 的自主操作涉及用户数据安全和系统权限。每一次涉及敏感操作（如发送邮件、访问通讯录、修改系统设置），Agent UI 都应该明确展示操作内容、影响范围、风险等级，并等待用户确认。

原则四：渐进式披露（Progressive Disclosure）

Agent 的操作往往涉及大量中间状态和技术细节。如果全部展示给用户，会造成信息过载。Agent UI 应该采用渐进式披露策略：默认展示高层摘要（如"正在搜索航班"），用户需要时可以展开查看详细信息（如"正在调用 XX 航空 API，参数为..."）。

原则五：错误友好（Error-Friendly）

Agent 在复杂任务中必然会遇到错误——API 超时、权限不足、数据格式不匹配、外部服务不可用。Agent UI 不应该将错误隐藏或简单显示为"出错了"，而应该：明确说明错误原因、展示受影响的范围、提供恢复选项（重试、跳过、手动处理）。

Agent UI 框架的架构设计经历了三个阶段的演进，每个阶段都对应着 Agent 技术能力和用户需求的升级。

第一代：对话框包装器（Chat Wrapper）

最早的 Agent UI 就是在现有聊天应用上包装一层 LLM API。用户发送消息，调用 API，显示回复。这种模式极其简单，但几乎不提供任何 Agent 特有的交互能力——没有进度显示、没有操作可视化、没有权限控制。

代表产品：早期的 ChatGPT Web、Claude Web、各类基于 OpenAI API 的聊天应用。

第二代：任务面板（Task Dashboard）

随着 Agent 开始具备多步任务执行能力，UI 进化为任务面板模式：用户下达指令后，界面展示一个任务卡片，卡片内包含步骤列表、状态指示、操作按钮（暂停、重试、取消）。

这种模式显著提升了 Agent 操作的透明度和可控性，但仍有局限：每个任务都是孤立的，任务之间的关联和依赖无法在界面上表达；多个任务的并发管理也缺乏统一的界面支持。

代表产品：Claude Code 的终端界面、OpenAI 的 ChatGPT Tasks 功能。

第三代：分层架构（Layered Architecture）

这是当前 Agent UI 框架的主流架构模式，也是 AGenUI 采用的设计。分层架构将 Agent UI 拆分为四个独立的层：

渲染层（Rendering Layer）：负责将 Agent 的状态和操作可视化为界面组件。包括步骤时间线、状态卡片、日志面板、权限确认弹窗等。这一层是平台相关的——iOS 用 SwiftUI，Android 用 Compose，HarmonyOS 用 ArkUI。

状态管理层（State Management Layer）：维护 Agent 的运行时状态——当前任务、步骤进度、错误信息、用户干预指令。这一层需要支持响应式更新——状态变化时自动触发界面刷新。

通信层（Communication Layer）：处理 Agent UI 与 Agent 后端之间的双向通信。包括：接收 Agent 的状态推送、发送用户的干预指令、处理实时流式响应。

适配层（Adaptation Layer）：这是跨平台 Agent UI 框架的核心价值所在。适配层将平台无关的 UI 描述转换为平台原生组件。开发者只需编写一次 UI 逻辑，适配层自动在 iOS、Android、HarmonyOS 上生成对应的原生界面。

分层架构的优势在于关注点分离（Separation of Concerns）：渲染层只需要关心"怎么展示"，状态管理层只需要关心"当前状态是什么"，通信层只需要关心"数据怎么传输"，适配层只需要关心"怎么跨平台"。各层之间通过明确的接口交互，可以独立演进和替换。

AGenUI（Agent GUI）是高德于 2026 年 5 月开源的 Agent UI 框架，它的核心创新在于：使用统一的 UI 描述语言（UI Description Language）实现了 iOS、Android、HarmonyOS 三端的 Agent 界面一次编写、三端运行。

AGenUI 的架构设计：

AGenUI 的核心是一个声明式 UI 描述系统。开发者使用 JSON Schema 或 TypeScript DSL 定义 Agent 的界面结构——包括布局、组件、交互逻辑、状态绑定。AGenUI 的编译器将这份描述转换为三个平台各自的原生代码：

• iOS → SwiftUI 代码
• Android → Jetpack Compose 代码
• HarmonyOS → ArkUI（方舟 UI）代码

为什么选择编译而非解释？ AGenUI 团队在技术文档中明确说明：编译时转换相比运行时解释有三个关键优势：

性能优势：编译生成的是原生代码，直接运行在平台的渲染引擎上，没有额外的运行时开销。运行时解释方案需要在应用启动时加载解释器、解析 UI 描述、动态创建组件——这会显著增加启动延迟和内存占用。

类型安全：编译时可以检测类型错误、属性缺失、不兼容的组件组合。运行时解释方案只能在运行时报错，而且错误信息往往不够精确。

开发体验：编译后的代码可以接入平台的原生开发工具链——Xcode 的预览、Android Studio 的布局检查器、DevEco Studio 的 ArkUI 预览器。开发者可以利用平台的原生工具进行调试和优化。

AGenUI 的组件系统：

AGenUI 提供了一套专为 Agent 场景设计的组件库：

AgentStepCard：展示单个任务步骤的卡片组件，包含步骤名称、状态图标（进行中/已完成/失败/跳过）、执行时间、详细信息（可展开）。

AgentTimeline：将多个步骤组织为垂直时间线，直观展示任务的整体进度。支持折叠/展开、步骤筛选（只看失败的步骤）、时间排序。

AgentPermissionDialog：标准化的权限确认对话框，展示操作描述、影响范围、风险等级（低/中/高），以及确认/拒绝/稍后决定三个操作按钮。

AgentLogStream：实时日志流组件，以滚动列表形式展示 Agent 执行的详细日志。支持日志级别过滤（INFO/WARN/ERROR）、关键词搜索、日志导出。

AgentActionPanel：操作面板组件，提供暂停、恢复、重试、取消、注入指令等用户干预操作。面板的可用操作根据 Agent 的当前状态动态变化。

AGenUI 的状态管理：

AGenUI 采用单向数据流（Unidirectional Data Flow）模式。Agent 后端通过 WebSocket 或 Server-Sent Events（SSE）推送状态更新，AGenUI 的状态管理层接收更新后，自动触发渲染层的界面刷新。

状态对象的结构遵循有限状态机（Finite State Machine, FSM）模型：每个步骤有明确的状态枚举（idle → running → completed / failed / skipped），状态转换有严格的规则（如 completed 不能回到 running）。这确保了界面始终反映 Agent 的真实状态。

状态管理是 Agent UI 框架中最复杂的技术挑战之一。与传统的 CRUD 应用不同，Agent 的状态具有动态性、异步性和不可预测性——你无法预先知道 Agent 将执行多少步骤、每步需要多长时间、会遇到什么错误。

有限状态机（FSM）模型：

Agent UI 的状态管理通常采用有限状态机模型。每个任务步骤被建模为一个状态机，包含以下状态：

• idle（空闲）：步骤尚未开始
• running（执行中）：步骤正在执行
• completed（已完成）：步骤成功完成
• failed（失败）：步骤执行失败
• skipped（已跳过）：步骤被跳过（可能因为前置步骤失败）
• paused（已暂停）：步骤被用户暂停
• waiting（等待中）：步骤等待用户输入或确认

状态转换遵循严格规则：

idle → running（Agent 开始执行）
idle → skipped（前置步骤失败，本步骤被跳过）
running → completed（执行成功）
running → failed（执行失败）
running → paused（用户暂停）
running → waiting（等待用户确认权限）
paused → running（用户恢复）
failed → running（用户要求重试）
waiting → running（用户确认）
waiting → skipped（用户拒绝）

响应式更新机制：

当 Agent 后端推送状态更新时，Agent UI 需要高效地更新界面。这里有两种主流的响应式更新方案：

方案一：拉模式（Pull / Polling）

UI 定期向 Agent 后端查询当前状态（如每 500ms 一次）。这种方式实现简单，但存在延迟和资源浪费——大部分查询返回的是相同的状态（空转），只在状态变化时才有意义。

方案二：推模式（Push / Streaming）

Agent 后端在状态变化时主动推送更新到 UI。通过 WebSocket 或 Server-Sent Events（SSE）实现实时通信。这种方式延迟极低（毫秒级），资源利用率高（只在需要时传输数据），但实现复杂度更高——需要处理连接断开、重连、消息顺序等问题。

AGenUI 的选择：采用推模式为主、拉模式为辅的混合方案。正常情况下通过 WebSocket 接收实时状态推送；当 WebSocket 连接断开时，自动切换到轮询模式，直到连接恢复。这种混合方案兼顾了实时性和可靠性。

状态同步的挑战：

在多设备场景下（用户同时在手机和平板上查看 Agent 状态），状态同步变得更加复杂。如果用户在平板上暂停了 Agent，手机上的界面需要立即反映这一变化。

解决方案是引入状态版本控制（State Versioning）：每次状态更新都携带一个版本号（单调递增），UI 收到更新后，只接受版本号更高的更新。这样可以避免乱序消息导致的状态不一致。

状态管理的代码实现：

// Agent UI 状态机实现示例
class AgentStepStateMachine {
  private state: StepState = 'idle';
  private version: number = 0;
  private listeners: Array<(state: StepState, version: number) => void> = [];

  // 状态转换规则
  private transitions: Record<StepState, StepState[]> = {
    idle: ['running', 'skipped'],
    running: ['completed', 'failed', 'paused', 'waiting'],
    completed: [],
    failed: ['running'],
    paused: ['running'],
    waiting: ['running', 'skipped'],
    skipped: [],
  };

  transition(newState: StepState): boolean {
    const allowed = this.transitions[this.state];
    if (!allowed.includes(newState)) {
      console.warn(`Invalid transition: ${this.state} → ${newState}`);
      return false;
    }
    this.state = newState;
    this.version++;
    this.notifyListeners();
    return true;
  }

  onStateChange(listener: (state: StepState, version: number) => void) {
    this.listeners.push(listener);
  }

  private notifyListeners() {
    for (const listener of this.listeners) {
      listener(this.state, this.version);
    }
  }
}

这个状态机实现确保了状态转换的合法性——只有符合预定义规则的转换才会被接受。同时，版本号（version）的单调递增确保了状态更新的有序性，即使在乱序到达的情况下也能正确处理。

Agent 的自主操作能力带来了独特的安全挑战。与人类用户不同，Agent 可以高速、批量、自动化地执行操作——如果权限控制不当，一个配置错误的 Agent 可能在几秒钟内造成大规模数据泄露或不可逆的系统变更。

Agent UI 的安全模型包含三个层次：

第一层：操作分类与风险评级

Agent 的每个操作都应该被分类并赋予风险等级：

• 低风险（Low）：只读操作——查询天气、搜索信息、读取日程。这些操作不修改任何数据，不需要用户确认。
• 中风险（Medium）：创建操作——新建日程、发送草稿邮件、创建文档。这些操作创建了新的数据，但不会修改或删除现有数据。建议展示确认提示，但允许用户设置为「自动执行」。
• 高风险（High）：修改/删除操作——发送邮件、删除文件、修改系统设置。这些操作会永久改变数据或系统状态，必须获得用户的显式确认。
• 极高风险（Critical）：涉及资金、隐私、安全的操作——转账、分享联系人、修改密码。这些操作需要二次确认（如输入密码或生物识别验证）。

第二层：权限请求的 UI 呈现

Agent UI 需要为不同风险等级的操作提供差异化的权限确认界面：

对于中风险操作，可以使用轻量级提示（Toast 或底部弹出条），展示操作摘要和「撤销」按钮。用户不需要主动确认，但可以事后撤销。

对于高风险操作，必须使用模态对话框（Modal Dialog），明确展示操作的完整信息（操作类型、影响范围、不可逆性），并要求用户主动点击确认。

对于极高风险操作，需要在模态对话框的基础上增加二次验证步骤——如要求用户输入密码、指纹验证或面部识别。

第三层：操作审计日志

Agent UI 应该维护一份完整的操作审计日志（Audit Log），记录 Agent 执行的每一个操作——包括：操作时间、操作类型、操作参数、执行结果、用户确认状态。

审计日志的价值在于：当出现安全问题时，可以追溯Agent 的完整操作历史，定位问题根源。同时，审计日志也是用户信任的重要来源——用户可以看到 Agent 到底做了什么，而不是仅凭 Agent 的一面之词。

AGenUI 的安全设计：

AGenUI 在框架层面内置了权限控制组件（PermissionGuard），开发者只需在定义操作时指定风险等级，框架自动渲染对应的确认界面。同时，AGenUI 提供审计日志导出功能，支持将操作日志导出为 JSON 或 CSV 格式，方便用户存档和审计。

Agent UI 的性能优化与传统应用有所不同——核心挑战不是首屏加载速度，而是长时间运行任务中的状态更新效率和多组件并发渲染的流畅度。

挑战一：高频状态更新的渲染性能

一个复杂的 Agent 任务可能包含数十个步骤，每个步骤在执行过程中可能产生数十条状态更新（进度百分比、子步骤状态、中间结果）。如果每次状态更新都触发全量界面重渲染，性能将迅速恶化。

优化方案一：差异更新（Diff-based Update）

只更新发生变化的 UI 部分，而不是重渲染整个界面。AGenUI 使用 Fine-grained Reactivity（细粒度响应式）技术——每个 UI 组件订阅特定的状态字段，只有当订阅的字段发生变化时，该组件才会重新渲染。

优化方案二：批量更新（Batching）

当 Agent 在短时间内产生多次状态更新时，将它们合并为一次批量更新。例如，Agent 在 100ms 内更新了 5 个步骤的状态，UI 不应该渲染 5 次，而应该在 100ms 后一次性渲染所有变化。

挑战二：长任务中的内存管理

Agent 执行长时间任务（如数据分析、批量处理）时，可能产生大量中间数据（日志、临时结果、缓存）。如果这些数据全部保存在内存中，可能导致内存泄漏或应用崩溃。

优化方案：实现内存水位线管理——当 Agent UI 的内存使用超过阈值时，自动清理旧日志和非关键缓存。同时提供日志分页（Pagination）功能——只加载最近 N 条日志到界面，旧日志存储在磁盘或数据库中，按需加载。

挑战三：多平台性能一致性

同一套 Agent UI 描述在 iOS、Android、HarmonyOS 上编译后，性能表现可能不一致。例如，iOS 的 SwiftUI 渲染引擎对某些组件的优化优于 Android 的 Compose。

优化方案：AGenUI 提供平台级性能调优接口（Platform Tuning API），允许开发者针对特定平台调整渲染策略、动画帧率、内存分配。例如，在低端 Android 设备上自动降低动画帧率，在 iOS 上启用更精细的布局优化。

测试 Agent UI 比测试传统应用困难得多——因为 Agent 的操作路径是非确定性的。同一个用户指令，Agent 可能选择不同的执行顺序、遇到不同的中间状态、产生不同的错误。

挑战：非确定性使得传统 UI 测试方法失效

传统的 UI 测试依赖预期结果（Expected Outcome）——给定输入 A，界面应该显示结果 B。但 Agent UI 中，给定输入 A，界面可能显示结果 B、C 或 D，取决于 Agent 的决策和外部环境。

解决方案一：基于场景的测试（Scenario-based Testing）

不测试「具体显示什么」，而是测试「在特定场景下界面行为是否正确」。例如：

• 场景：Agent 执行到第 3 步时失败。
• 验证：界面上第 3 步显示「失败」状态，后续步骤显示「已跳过」，操作面板提供「重试」按钮。

这种测试方法关注的是界面的响应逻辑而非具体的显示内容，因此不受 Agent 非确定性的影响。

解决方案二：状态驱动测试（State-driven Testing）

直接模拟 Agent 的状态变化，验证界面是否正确响应。测试框架发送预设的状态序列（如 idle → running → completed），然后检查界面的视觉输出是否符合预期。

这种方法的优点是完全可控——不依赖真实的 Agent 后端，测试速度快、结果可重复。缺点是无法覆盖真实 Agent 的所有状态变化组合。

解决方案三：模糊测试（Fuzz Testing）

向 Agent UI 发送随机的状态变化序列，检测界面是否出现崩溃、显示异常、状态不一致。这种方法可以发现边界情况下的 bug——如快速连续的状态切换、异常状态值、空数据场景。

AGenUI 的测试工具：

AGenUI 内置了 Agent UI Tester 工具，支持以上三种测试方法的自动化执行。开发者只需定义测试场景或状态序列，测试工具自动在 iOS、Android、HarmonyOS 三个平台上执行测试，并生成跨平台对比报告。

截至 2026 年 5 月，主流的 Agent UI 框架包括 AGenUI、Vercel AI SDK 的 UI 组件、LangGraph 的 Studio、以及各平台的原生 Agent UI 方案。以下是系统性对比：

AGenUI（高德开源）：

优势：三端覆盖（iOS、Android、HarmonyOS），专为 Agent 设计的完整组件库（步骤时间线、权限确认、日志流），声明式 UI 描述降低了开发门槛，内置安全模型和审计日志。

劣势：仅支持移动端（不覆盖 Web 和桌面），相对较新（2026 年 5 月开源），社区生态还在建设中，文档和教程不够丰富。

适用场景：移动优先的 Agent 应用，需要覆盖国内三大移动操作系统（尤其是需要 HarmonyOS 支持的项目）。

Vercel AI SDK UI：

优势：Web 优先，与 Next.js 生态深度集成，流式 UI 生成（Streaming UI）能力强大，社区活跃，文档完善。

劣势：仅支持 Web 平台（React），不是专为 Agent 设计的通用框架（更多是 LLM 对话界面的增强），移动端需要额外的适配工作。

适用场景：Web 端 AI 应用，特别是基于 Next.js 的项目。

LangGraph Studio：

优势：Agent 工作流可视化能力强大，支持多 Agent 协作的图形化展示，与 LangGraph 框架原生集成。

劣势：主要是开发调试工具而非面向终端用户的 UI 框架，定制化能力有限，不适合直接用于生产环境的用户界面。

适用场景：开发阶段的 Agent 调试和可视化，不适合直接面向终端用户。

平台原生方案（Apple Intelligence UI、Android AI Core UI）：

优势：系统级集成，与操作系统深度绑定，性能最优，用户体验最自然（与系统其他应用一致的交互模式）。

劣势：平台锁定（Apple 方案只能用于 iOS/macOS，Android 方案只能用于 Android），跨平台开发需要为每个平台独立实现。

适用场景：单一平台深度优化的项目，特别是 Apple 生态或 Android 生态的独占应用。

选择建议：

• 如果你的 Agent 应用主要在移动端使用，且需要覆盖三大移动操作系统 → 选择 AGenUI。
• 如果你的 Agent 应用主要在 Web 端使用 → 选择 Vercel AI SDK UI。
• 如果你在开发阶段需要可视化和调试 Agent 工作流 → 选择 LangGraph Studio。
• 如果你只需要在单一平台上提供最佳体验 → 选择平台原生方案。

Agent UI 框架正在经历从「界面构建工具」到「交互范式定义者」的演进。以下是未来 1-2 年内最值得关注的趋势：

趋势一：自然语言界面（Natural Language UI）

未来的 Agent UI 可能不再需要传统的按钮、菜单和表单——用户通过自然语言描述需求，Agent 自动生成界面来展示信息和收集输入。这种「动态界面」（Dynamic UI）将根据上下文实时生成，而不是预先设计。

趋势二：多模态 Agent UI

Agent UI 将从纯文本和图形扩展到语音、手势、眼动等多模态交互。用户可以说出指令、用手势确认操作、用眼动选择选项。AGenUI 等框架需要为多模态交互提供标准化的组件和协议。

趋势三：Agent-to-Agent 界面

当多个 Agent 需要协同工作时，Agent 之间的交互界面也变得重要。这不是面向人类用户的界面，而是Agent 之间的状态共享、任务协调、冲突解决的可视化界面。这种界面主要面向开发者和管理员，用于监控和调试多 Agent 系统。

趋势四：可组合 Agent UI（Composable Agent UI）

未来的 Agent UI 将采用可组合架构——不同的 UI 组件（步骤时间线、权限确认、日志流、操作面板）可以像积木一样组合和复用。开发者可以根据 Agent 的具体能力和用户需求，灵活组合不同的 UI 组件，而不是使用固定的模板。

趋势五：AI 辅助的 Agent UI 设计

Agent UI 的设计过程本身也将被 AI 辅助——开发者用自然语言描述「我需要一个 Agent UI，包含步骤时间线和权限确认」，AI 自动生成对应的 UI 描述代码。这种「UI 即代码」（UI as Code）的理念将进一步降低 Agent UI 的开发门槛。

AGenUI 的未来路线图：

根据高德开源团队的技术规划，AGenUI 在 2026 年下半年计划支持：

• Web 端适配（基于 React 和 Vue）
• 多模态输入组件（语音输入、手写输入）
• Agent-to-Agent 协调界面
• AI 辅助的 UI 代码生成
• 更丰富的组件库（数据可视化、地图集成、3D 展示）

对开发者的建议：

Agent UI 是一个快速演进的领域，今天的最佳实践可能在半年后就不再适用。保持对以下信号的关注：主流框架的更新、头部公司的产品实践、学术研究的新发现、开源社区的新工具。

本节通过一个完整的实战示例，演示如何使用 AGenUI 构建一个智能出行规划的 Agent UI 界面。这个示例涵盖了 AGenUI 的核心功能：步骤时间线、权限确认、操作面板和日志流。

第一步：定义 Agent 任务

首先，我们需要定义 Agent 的任务结构——包括步骤列表、每个步骤的参数、需要用户确认的操作。

import { AgentUI, StepCard, Timeline, PermissionDialog, LogLevel } from '@agenui/core';

const travelPlannerUI = AgentUI.define({
  title: "智能出行规划助手",
  description: "自动搜索航班、酒店和当地交通，为你规划最优出行方案",
  icon: "🧳",
});

第二步：构建步骤时间线

const timeline = Timeline.of([
  StepCard.of({
    id: "search-flights",
    title: "搜索最优航班",
    icon: "✈️",
    status: "completed",
    details: {
      bestOption: "国航 CA1234，北京→上海，08:00-10:15，¥680",
      alternatives: 3,
    },
  }),
  StepCard.of({
    id: "search-hotels",
    title: "搜索推荐酒店",
    icon: "🏨",
    status: "running",
    details: {
      searching: ["万豪", "希尔顿", "洲际"],
      progress: "45%",
    },
  }),
  StepCard.of({
    id: "confirm-booking",
    title: "确认预订",
    icon: "💳",
    status: "idle",
    requiresPermission: true,
    permission: PermissionDialog.of({
      title: "确认出行预订",
      riskLevel: "high",
      description: "航班 ¥680 + 酒店 ¥1,200（2晚），总计 ¥1,880",
      actions: ["confirm", "reject", "modify"],
    }),
  }),
]);

第三步：配置操作面板和日志

const config = {
  actionPanel: {
    actions: ["pause", "cancel", "inject"],
    injectPrompt: "调整出行偏好（如预算、时间、偏好）...",
  },
  logStream: {
    enabled: true,
    defaultCollapsed: true,
    maxLines: 200,
    levels: [LogLevel.Info, LogLevel.Warn, LogLevel.Error],
  },
};

第四步：连接 Agent 后端

import { AgentConnector } from '@agenui/core';

const connector = new AgentConnector({
  url: "wss://your-agent-server.com/ws",
  reconnectPolicy: {
    maxRetries: 5,
    backoffMs: 1000,
    maxBackoffMs: 30000,
  },
});

// 连接状态变化时更新 UI
connector.onStateChange((state) => {
  timeline.updateStatus("connection", state);
});

// 接收 Agent 推送的步骤更新
connector.onStepUpdate((update) => {
  timeline.updateStep(update.stepId, update);
});

// 发送用户干预指令
connector.sendCommand("pause", { reason: "用户手动暂停" });

这个示例展示了 AGenUI 的核心工作流：定义任务 → 构建界面 → 配置交互 → 连接后端。整个过程采用了声明式的描述方式，开发者不需要关心各平台的具体实现细节——AGenUI 的编译器会自动处理跨平台适配。

本文总结：

Agent UI 框架是 AI Agent 从「聊天工具」走向「操作系统级应用」的关键基础设施。它解决了 Agent 交互中的核心挑战——可观测性、可干预性、权限控制和跨平台适配。

AGenUI 作为首个覆盖 iOS、Android、HarmonyOS 三端的开源 Agent UI 框架，代表了 Agent UI 从「实验性探索」到「工业级标准」的重要里程碑。它的声明式 UI 描述、内置安全模型、分层架构设计为开发者提供了高效构建跨平台 Agent 界面的完整工具链。

关键要点回顾：

1. 设计原则：可观测性优先、可干预性、权限透明、渐进式披露、错误友好——这五大原则是 Agent UI 设计的基础。
2. 架构模式：分层架构（渲染层、状态管理层、通信层、适配层）是 Agent UI 框架的最佳实践，支持关注点分离和独立演进。
3. 跨平台策略：AGenUI 通过编译时转换（而非运行时解释）将声明式 UI 描述转换为各平台原生代码，兼顾了性能和开发效率。
4. 状态管理：有限状态机 + 响应式更新 + 状态版本控制是 Agent UI 状态管理的核心技术栈。
5. 安全模型：操作分类与风险评级 + 差异化权限确认 + 操作审计日志构成 Agent UI 的三层安全体系。
6. 未来趋势：自然语言界面、多模态交互、Agent-to-Agent 界面、可组合架构、AI 辅助设计——Agent UI 正在从「界面构建工具」演变为「交互范式定义者」。

扩展阅读：

• 本站《AI Agent 入门：从概念到实现》—— 理解 AI Agent 的基本概念和实现路径
• 本站《Multi-Agent 系统设计与协作》—— 多智能体系统的架构设计
• 本站《AI Agent 浏览器操作能力》—— Agent 如何通过浏览器自动化执行任务
• 本站《12-Factor Agents 工程原则》—— Agent 应用的工程化最佳实践
• AGenUI 官方文档（GitHub）：声明式 UI 描述的完整 API 参考
• Apple Human Interface Guidelines：AI 界面设计指南
• Google Material Design 3：AI 组件设计规范