---
title: "事件模型"
description: "1.0 基础协议：事件信封、通用字段、标识符与全部事件地图。"
---

> 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/basic/run-input/)：反向传输的唯一消息
- [**元数据**](https://ag-ui.ndjp.net/spec/1-0/basic/metadata/)：一切之上的开放通道及合并规则
- [**能力**](https://ag-ui.ndjp.net/spec/1-0/basic/capabilities/)：智能体在运行前对自身的声明，以及声明带来的义务
- [**事件模式**](https://ag-ui.ndjp.net/spec/1-0/basic/patterns/)：事件组合成流的方式
- [**传输**](https://ag-ui.ndjp.net/spec/1-0/basic/transports/)：流如何成帧与投递
- [**处理模型**](https://ag-ui.ndjp.net/spec/1-0/basic/processing/)：消费者遇到不认识内容时的行为

## 事件

每个事件都是一个共享同一信封的 JSON 对象，schema 中定义为 `BaseEvent`：

- `type` —— **REQUIRED**。判别符，`EventType` 的 31 个值之一。本规范的每条规则都通过该字段附着到事件上。
- `timestamp` —— OPTIONAL。事件创建时间。信息性的：消费者 MUST NOT 用它排序事件——**到达顺序才是协议的顺序**。约定单位为 Unix 纪元毫秒。
- `rawEvent` —— OPTIONAL。该事件翻译自的提供商原生事件，原样携带。消费者 MUST NOT 从中推导协议行为。
- `metadata` —— OPTIONAL。见[通用字段](#通用字段)。

## 通用字段

### `metadata`

一切之上的开放通道：按 key 开放、key 下允许任何 JSON 值、在构建同一项的事件之间累积——逐 key、最后写入胜出、不递归——按族指定合并目标，并保留 `ag-ui` key。详见[元数据](https://ag-ui.ndjp.net/spec/1-0/basic/metadata/)。

### 缺省即缺省

这适用于每个可选字段，包括携带任意 JSON 的字段，如 `rawEvent`、`RUN_FINISHED.result` 与 `forwardedProps`。**整个可选字段被设为 `null` 时必须省略。** 必填 JSON 载荷可以是 `null`，例如 `CUSTOM.value` 或 `STATE_SNAPSHOT.snapshot`。

## 标识符

- `threadId` 标识一段会话。由应用铸造，跨运行稳定。
- `runId` 标识一次运行。**MUST NOT** 在同一线程的另一次运行中复用。
- `messageId` 标识一条消息。它跨越运行边界——后续运行中的快照 MAY 按 id 重述一条消息——因此它 MUST 在其线程内唯一。
- `toolCallId` 标识一次工具调用，并把其结果以及任何关于它的中断关联回该调用。
- `subagentRunId` 是子智能体**一次调用**的不透明句柄，不是可复用的定义名：同一子智能体的两次调用携带两个不同的值。

所有标识符都是**不透明字符串**：消费者 MUST NOT 从中解析结构。

## 事件

31 种事件类型，分属八个族：

| 族 | 事件 | 模式 |
| --- | --- | --- |
| [运行与步骤](https://ag-ui.ndjp.net/spec/1-0/events/lifecycle/) | `RUN_STARTED` `RUN_FINISHED` `RUN_ERROR` `STEP_STARTED` `STEP_FINISHED` | 生命周期 |
| [文本消息](https://ag-ui.ndjp.net/spec/1-0/events/text-messages/) | `TEXT_MESSAGE_START` `TEXT_MESSAGE_CONTENT` `TEXT_MESSAGE_END` `TEXT_MESSAGE_CHUNK` | [流式](https://ag-ui.ndjp.net/spec/1-0/basic/patterns/streaming/) |
| [工具调用](https://ag-ui.ndjp.net/spec/1-0/events/tool-calls/) | `TOOL_CALL_START` `TOOL_CALL_ARGS` `TOOL_CALL_END` `TOOL_CALL_CHUNK` `TOOL_CALL_RESULT` | [流式](https://ag-ui.ndjp.net/spec/1-0/basic/patterns/streaming/) |
| [推理](https://ag-ui.ndjp.net/spec/1-0/events/reasoning/) | `REASONING_START` `REASONING_END` `REASONING_MESSAGE_START` `REASONING_MESSAGE_CONTENT` `REASONING_MESSAGE_END` `REASONING_MESSAGE_CHUNK` `REASONING_ENCRYPTED_VALUE` | [流式](https://ag-ui.ndjp.net/spec/1-0/basic/patterns/streaming/) |
| [状态](https://ag-ui.ndjp.net/spec/1-0/events/state/) | `STATE_SNAPSHOT` `STATE_DELTA` `MESSAGES_SNAPSHOT` | [快照–增量](https://ag-ui.ndjp.net/spec/1-0/basic/patterns/snapshots/) |
| [活动](https://ag-ui.ndjp.net/spec/1-0/events/activity/) | `ACTIVITY_SNAPSHOT` `ACTIVITY_DELTA` | [快照–增量](https://ag-ui.ndjp.net/spec/1-0/basic/patterns/snapshots/) |
| [子智能体](https://ag-ui.ndjp.net/spec/1-0/events/subagents/) | `SUBAGENT_STARTED` `SUBAGENT_FINISHED` `SUBAGENT_ERROR` | 生命周期 |
| [透传](https://ag-ui.ndjp.net/spec/1-0/events/passthrough/) | `RAW` `CUSTOM` | 独立 |

## Schema

协议的完整结构由 [`/spec/1-0/schema.json`](https://docs.ag-ui.com/spec/1-0/schema.json) 中的 JSON Schema 定义。它是唯一事实来源：TypeScript、Python 与 .NET 模型都由它生成。本文档提到某个字段时，是在命名 schema 定义的东西，而非重述其形状。

schema 刻意不表达本文档所说的内容：顺序、生命周期、归因、错误处理与兼容性属于行为，schema 无法表达。若两者在结构上冲突，schema 胜出，本文档有缺陷。

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