---
title: "活动"
description: "1.0：UI 作为独立控件渲染的结构化进度，保留在消息序列中。"
---

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

# 活动

活动是**不属于会话内容**的结构化进度——正在运行的搜索、逐步填写的清单、UI 作为独立控件渲染的步骤。它被物化为消息以保留其在序列中的位置，但其内容是对象，不是文本。

## 事件

活动绑定[快照–增量模式](https://ag-ui.ndjp.net/spec/1-0/basic/patterns/snapshots/)，作用域为每条活动消息，按 `messageId` 匹配。

### `ACTIVITY_SNAPSHOT`

创建或替换一条活动消息。

```json
{
  "type": "ACTIVITY_SNAPSHOT",
  "messageId": "act-1",
  "activityType": "web_search",
  "content": { "query": "…", "found": 3 }
}
```

- `activityType` 是开放字符串：集合属于生产者，不属于协议。消费者 MUST 容忍它不认识的类型。
- 对消费者未见过的 `messageId` 的快照会创建活动消息，序列位置为到达点。
- 对已存在活动的快照替换其内容与 `activityType`。`replace` 是 OPTIONAL；缺省表示替换，且该含义是规范性的。
- 显式 `replace: false` 要求消费者保持现有消息原样——**内容与 `activityType` 皆然**；快照自己的值只在它创建消息时适用。它不是合并。
- 替换替换的是**内容**，不是迄今累积的元数据——元数据继续按[元数据规则](https://ag-ui.ndjp.net/spec/1-0/basic/metadata/)合并。归因是例外：替换性快照会重新铸造活动，因此消息的 `subagentRunId` 变为快照自己的，包括变为缺省。
- 对已存在活动的 `replace: false` 快照不会重新铸造所有权：已确立的所有者成立，快照自己的归因 MUST 与之一致。生产者义务与[子智能体规则](https://ag-ui.ndjp.net/spec/1-0/events/subagents/)对流转延续的要求相同；消费者义务刻意更弱——已确立的所有者成立，不要求消费者拒绝不一致，而流转延续的不匹配必须被拒绝。

### `ACTIVITY_DELTA`

用针对某条活动消息的 RFC 6902 patch 修订其内容。delta 的 `activityType` 替换消息的——delta MAY 重新类型化它所修订的活动，不打算重类型化的 delta MUST 重复当前类型，因为该字段必填。

- 生产者 MUST NOT 为它未用快照创建的活动消息发送 delta——快照是[模式](https://ag-ui.ndjp.net/spec/1-0/basic/patterns/snapshots/)要求的基线。
- 命名不存在消息、或非活动消息的 delta 被跳过；消费者 SHOULD 发出警告，MUST NOT 让运行失败。
- patch 后的结果 MUST 仍是对象：`content` 按 schema 是对象，生产者 MUST NOT 发送会使它变成其他东西的 patch（例如根替换）。不要求消费者检测该违规。
- patch 失败处理属于[模式](https://ag-ui.ndjp.net/spec/1-0/basic/patterns/snapshots/#当-patch-无法应用)，通过同一 `messageId` 的新快照重新同步。

## 会话中的活动消息

活动消息以固定 role `activity` 出现在历史中。它是消费者的渲染材料，不是智能体据此恢复的会话：消费者 MUST 在[运行输入](https://ag-ui.ndjp.net/spec/1-0/basic/run-input/)发送的 `messages` 中剥离活动消息。活动消息如何经受 `MESSAGES_SNAPSHOT`，在该[事件](https://ag-ui.ndjp.net/spec/1-0/events/state/#messages_snapshot)处规定。

## 消息流

```text
Agent → UI: ACTIVITY_SNAPSHOT (act-1, "web_search", {query, found: 0})
UI: 搜索控件出现
Agent → UI: ACTIVITY_DELTA (act-1, replace /found → 3)
Agent → UI: ACTIVITY_DELTA (act-1, add /results/0 …)
UI: 控件就地更新
```

## 数据类型

`ActivitySnapshotEvent`、`ActivityDeltaEvent` 与 `ActivityMessage` 由 [schema 参考](https://docs.ag-ui.com/spec/1-0/schema)定义。`ActivityMessage` 独立存在而非组合基础消息，因为其内容是对象而不是字符串。

## 错误处理

格式错误的活动事件作为已知值的格式错误是致命的。两种被容忍的失败——针对缺失或非活动消息的 delta，以及格式良好但无法应用的 patch——如上警告并跳过；两者都可能使生产者与消费者就该活动产生分歧，由生产者的下一个快照修复。

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