跳到主要内容

状态管理

理解 AG-UI 中智能体与前端之间的共享状态模型、快照与增量同步机制。

状态管理是 AG-UI 的核心能力之一,用于在智能体与前端应用之间高效共享与同步结构化数据,使双方能够基于同一上下文协作。

共享状态模型

AG-UI 中的共享状态通常具备以下特征:

  • 结构化:以可序列化的数据对象表示(具体 schema 由应用与智能体约定)。
  • 可共享:智能体与前端都可以读取(并在允许时写入/影响)状态。
  • 跨交互持久:在一次会话或任务的多轮交互中持续存在。
  • 实时同步:通过事件流在执行过程中不断更新。

共享状态可用于:任务进度、表单草稿、计划步骤、检索结果集合、UI 面板数据、协作编辑上下文等。

同步方式

AG-UI 提供两种互补的状态同步机制:

1. 状态快照(STATE_SNAPSHOT)

  • 携带完整状态表示。
  • 常用于运行开始、重连恢复或需要强一致重建的场景。
  • 客户端通常应以快照内容替换本地对应状态(而非简单浅合并),以避免残留旧字段导致不一致。

2. 状态增量(STATE_DELTA)

  • 携带对当前状态的增量更新。
  • 通常采用 JSON Patch(RFC 6902) 操作序列表示变更(如 add/replace/remove 等)。
  • 优点是带宽效率高、更新粒度细,适合频繁变化的状态。

客户端应按事件顺序应用增量;若发现应用后状态异常或补丁无法匹配,可等待/请求新的快照进行校准(具体恢复机制取决于实现)。

消息快照(MESSAGES_SNAPSHOT)

除通用共享状态外,AG-UI 还支持通过 MESSAGES_SNAPSHOT 进行消息级全量同步。该事件可用于:

  • 在重连或切换视图时重建完整对话
  • 同步包含工具消息、活动消息、推理消息等在内的会话内容

不同消息类型在快照中的替换语义可能有特定规则(例如某些角色/类型的全量替换行为),实现时应遵循协议规范与 SDK 行为。

实践建议

  • 明确状态边界:区分“协议共享状态”“UI 本地状态”“服务端持久化状态”,避免混用导致同步混乱。
  • 设计可补丁化结构:合理组织对象与数组结构,使增量更新更稳定、易于追踪。
  • 处理并发与冲突:在多人协作或多来源更新场景下,定义冲突解决策略(以服务端为准、最后写入胜出或自定义合并等)。
  • 版本与兼容:状态 schema 演进时注意向后兼容,必要时通过快照重建完成迁移。
  • 可观测性:记录关键状态事件,便于调试同步问题与复现用户会话。

与其他能力的关系

  • 工具调用:工具参数与结果可能驱动状态变化,并通过状态事件反映到 UI。
  • 人机协同中断:用户在中断期间的编辑/审批结果可影响后续状态。
  • 生成式 UI:状态可作为声明式/组件化 UI 的数据源,实现动态界面更新。

Type to search…

↑↓ navigate↵ selectEsc close