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与时间戳建立索引以便快速检索