---
title: "序列化（Serialization）"
description: "序列化事件流，用于历史恢复、分支（时间旅行）与压缩。"
---

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

# 序列化（Serialization）

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

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

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

## 核心概念

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

## 更新后的事件字段

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

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

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

## 事件压缩

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

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

常见压缩规则：

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

## 分支与时间旅行

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

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

优势：

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

## 示例

### 基础序列化

```ts
// 序列化事件流
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)
```

### 事件压缩

压缩前：

```ts
[
  { 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 } },
]
```

压缩后：

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

### 使用 `parentRunId` 分支

```ts
// 原始运行
{
  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"] },
}
```

### 规范化输入

```ts
// 首次运行包含完整消息
{
  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`](https://ag-ui.ndjp.net/concepts/metadata/) 对象，它是你序列化内容的一部分——请与其他内容一并持久化，否则回放流会缺少 token 用量、trace id 以及生产者附加的其他内容。

持久化时需了解两点：

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

## 实现说明

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

## 另见

- [事件机制](https://ag-ui.ndjp.net/concepts/events/)、[元数据](https://ag-ui.ndjp.net/concepts/metadata/)、[状态管理](https://ag-ui.ndjp.net/concepts/state/)
- [SDK 与客户端](https://ag-ui.ndjp.net/sdk/)

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