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

> Documentation Index
> Fetch the complete documentation index at: https://ag-ui.ndjp.net/llms.txt
> Use this file to discover all available pages before exploring further.

# 状态管理

状态管理是 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 的数据源，实现动态界面更新。

Source: https://ag-ui.ndjp.net/concepts/state/index.mdx
