---
title: "快照与增量"
description: "1.0：演进值如何传输——整体替换，JSON Patch 修订。"
---

> 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.

# 快照与增量

生产者报告的某些内容不是文本流，而是会演进的值：智能体状态、活动内容、会话本身。它们以**快照**（替换）与**增量**（修订）传输。

三个族使用该模式：[状态](https://ag-ui.ndjp.net/spec/1-0/events/state/)（`STATE_SNAPSHOT`、`STATE_DELTA`，以及用于会话的 `MESSAGES_SNAPSHOT`）与[活动](https://ag-ui.ndjp.net/spec/1-0/events/activity/)（`ACTIVITY_SNAPSHOT`、`ACTIVITY_DELTA`）。本页陈述它们共有的内容；各族页面陈述各自替换与修订什么。

## 快照

快照携带完整值。消费者 MUST 用快照内容替换自己的副本——**快照不是合并**——除非快照本身通过其族定义的字段选择不替换（[活动](https://ag-ui.ndjp.net/spec/1-0/events/activity/)的 `replace: false` 是唯一情形）。

在它之前的增量都已作废：快照——无论被应用还是被拒绝——都是新的基线时刻。

生产者 MAY 在任何时候发送快照，并 SHOULD 在无法保证消费者基线与自身一致时发送：出错之后、增量无法表达的内容之后，或继续旧线程的运行开始时。

## 增量

增量修订当前值，表达为 [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902) JSON Patch：按序应用的操作数组，原子地——若任一操作失败，文档保持原样。

- 增量针对消费者当前值应用：最后一次快照经此后每个增量修订后的结果。对状态而言，运行起始值是输入的 `state`，当输入[未携带](https://ag-ui.ndjp.net/spec/1-0/basic/run-input/#state)时为 `{}`。
- 生产者 MUST NOT 为它未给消费者基线的值发送增量。什么算基线由族决定——状态从输入就有，活动只有在其首个快照之后才有。
- Patch 操作是刻意开放的对象：schema 如此标记，RFC 6902 未定义的成员是协议合法内容，[处理模型](https://ag-ui.ndjp.net/spec/1-0/basic/processing/) MUST NOT 剥离。

## 当 patch 无法应用

结构有效并不意味着 patch 可应用：格式良好的操作可能指向不存在的路径，RFC 6902 把这一点留给应用者。**格式错误的操作**——patch 不是数组、操作缺少必填成员或成员类型错误——是已知值的格式错误，与其他一样致命。`op` 命名 RFC 6902 未定义内容的操作不是格式错误，而是**未识别**——在本消费者发布之后加入的判别联合成员——[处理模型](https://ag-ui.ndjp.net/spec/1-0/basic/processing/)的列表规则适用：该元素从 patch 中丢弃并警告，运行存活。

格式良好但应用失败的 patch 又是另一回事：

- 消费者 MUST NOT 保留部分应用的结果——RFC 6902 应用是原子的。
- 消费者 MUST 暴露失败——给出足以诊断的警告，说明什么失败及原因——并 MAY 继续使用先前的值而非让运行失败。
- 失败的 `test` 操作属于同一情形：patch 不应用，消费者保留先前的值。

从那一刻起，消费者的值可能已与生产者分歧。得知或无法排除这一点的生产者 SHOULD 用快照重新同步；消费者 MUST 采用下一个快照，无论此前跳过了什么——这正是恢复得以可能的原因。

## 消息流

```text
Producer → Consumer: STATE_SNAPSHOT {"items": []}
Producer → Consumer: STATE_DELTA add /items/0
Producer → Consumer: STATE_DELTA replace /items/0/status
Consumer: 某个 delta 应用失败 → 警告，保留先前的值
Producer → Consumer: STATE_SNAPSHOT（重新同步）
```

## 数据类型

patch 形状——`JsonPatch`、其操作、`JsonPointer`——由 [schema 参考](https://docs.ag-ui.com/spec/1-0/schema)按 RFC 6902 引用定义。

Source: https://ag-ui.ndjp.net/spec/1-0/basic/patterns/snapshots/index.mdx
