跳到主要内容

序列化(Serialization)

序列化事件流,用于历史恢复、分支(时间旅行)与压缩。

AG-UI 中的序列化提供一种标准方式,用于持久化并恢复驱动智能体-UI 会话的事件流。借助序列化的流,你可以:

  • 在刷新或重连后恢复聊天历史与 UI 状态
  • 附加到正在运行的智能体并继续接收事件
  • 从任意先前运行创建分支(时间旅行)
  • 压缩存储的历史以减小体积而不丢失语义

本页说明模型、更新后的事件字段,以及实际使用模式与示例。

核心概念

  • 流序列化(Stream serialization):把完整事件历史与可移植表示(如 JSON)互相转换,以便存入数据库、文件或日志。
  • 事件压缩(Event compaction):把冗长的流缩减为快照,同时保持语义(如合并内容分片、把增量折叠为快照)。
  • 运行谱系(Run lineage):使用 parentRunId 跟踪会话分支,形成类似 git 的只追加日志,支持时间旅行与替代路径。

更新后的事件字段

RunStarted 事件包含额外的可选字段:

type RunStartedEvent = BaseEvent & {
  type: EventType.RUN_STARTED
  threadId: string
  runId: string
  /** 同一线程内用于分支/时间旅行的父运行 */
  parentRunId?: string
  /** 本次运行的确切智能体输入(可省略已在历史中的消息) */
  input?: AgentInput
}

这些字段支持谱系跟踪,并让实现能精确记录传给智能体的内容,独立于先前记录的消息。

事件压缩

压缩在保持相同可观察结果的前提下减少事件流中的噪声。典型实现提供一个工具函数:

declare function compactEvents(events: BaseEvent[]): BaseEvent[]

常见压缩规则:

  • 消息流:把 TEXT_MESSAGE_* 序列合并为单条消息快照;拼接同一消息相邻的 TEXT_MESSAGE_CONTENT
  • 工具调用:把工具调用的 start/content/end 折叠为紧凑记录
  • 状态:把连续的 STATE_DELTA 合并为单个最终 STATE_SNAPSHOT,丢弃被取代的更新
  • 运行输入规范化:从 RunStarted.input.messages 中移除流中较早出现的消息

分支与时间旅行

在 RunStarted 事件上设置 parentRunId 可创建类似 git 的谱系。流成为不可变的只追加日志,每次运行都可以从任意先前运行分支。

run1
 ├─ run2
 │   ├─ run3 (parent run2)
 │   │   └─ run4
 │   └─ run5 (parent run2)
 │       └─ run6

优势:

  • 同一序列化日志中的多个分支
  • 不可变历史(只追加)
  • 到任意点的确定性时间旅行

示例

基础序列化

// 序列化事件流
const events: BaseEvent[] = [...]
const serialized = JSON.stringify(events)

await storage.save(threadId, serialized)

// 之后恢复并压缩
const restored = JSON.parse(await storage.load(threadId))
const compacted = compactEvents(restored)

事件压缩

压缩前:

[
  { type: "TEXT_MESSAGE_START", messageId: "msg1", role: "user" },
  { type: "TEXT_MESSAGE_CONTENT", messageId: "msg1", delta: "Hello " },
  { type: "TEXT_MESSAGE_CONTENT", messageId: "msg1", delta: "world" },
  { type: "TEXT_MESSAGE_END", messageId: "msg1" },
  { type: "STATE_DELTA", patch: { op: "add", path: "/foo", value: 1 } },
  { type: "STATE_DELTA", patch: { op: "replace", path: "/foo", value: 2 } },
]

压缩后:

[
  {
    type: "MESSAGES_SNAPSHOT",
    messages: [{ id: "msg1", role: "user", content: "Hello world" }],
  },
  {
    type: "STATE_SNAPSHOT",
    state: { foo: 2 },
  },
]

使用 parentRunId 分支

// 原始运行
{
  type: "RUN_STARTED",
  threadId: "thread1",
  runId: "run1",
  input: { messages: ["Tell me about Paris"] },
}

// 从 run1 分支
{
  type: "RUN_STARTED",
  threadId: "thread1",
  runId: "run2",
  parentRunId: "run1",
  input: { messages: ["Actually, tell me about London instead"] },
}

规范化输入

// 首次运行包含完整消息
{
  type: "RUN_STARTED",
  runId: "run1",
  input: { messages: [{ id: "msg1", role: "user", content: "Hello" }] },
}

// 第二次运行省略已存在的消息
{
  type: "RUN_STARTED",
  runId: "run2",
  input: { messages: [{ id: "msg2", role: "user", content: "How are you?" }] },
  // msg1 被省略;它已存在于历史中
}

元数据

事件与消息携带可选的 metadata 对象,它是你序列化内容的一部分——请与其他内容一并持久化,否则回放流会缺少 token 用量、trace id 以及生产者附加的其他内容。

持久化时需了解两点:

  • 压缩会折叠它:折叠增量会合并其元数据,最后写入胜出。排序注意事项见事件压缩与压缩参考。
  • 二进制比 JSON 更窄:通过 protobuf,元数据是 google.protobuf.Struct,null、数组与嵌套对象可保留——但数字是 IEEE-754 double,超过 2^53 的整数会丢失精度,且若干事件类型根本没有 protobuf 表示。JSON 可精确往返一切。归档存储优先使用 JSON。

实现说明

  • 为压缩与(反)序列化提供 SDK 辅助函数
  • 以只追加方式存储流;尽可能使用增量写入
  • 持久化长历史时考虑压缩
  • 按 threadId、runId 与时间戳建立索引以便快速检索

另见

Type to search…

↑↓ navigate↵ selectEsc close