message_update 事件深入#

message_update 是 AgentEvent 系统中最特殊的事件：它既是高层事件，又携带底层事件；它既是业务边界，又包含技术细节。

理解 message_update，就是理解两层事件系统的连接点。

数据结构：两个关联字段#

message_update 的类型定义揭示了两层关系：

1
{
2
  type: "message_update";
3
  message: AgentMessage;                        // 高层累积状态
4
  assistantMessageEvent: AssistantMessageEvent; // 底层流事件
5
}

两个字段，两种视角：

message：当前累积的消息状态（业务层关心的”结果”）
assistantMessageEvent：当前触发的底层事件（技术层关心的”过程”)

每次底层事件触发时，message_update 同时携带：

底层事件的增量信息（delta）
高层消息的累积状态（message）

关联一：AgentMessage 类型树#

AgentMessage 是三种消息类型的联合：

1
AgentMessage
2
│
3
├── UserMessage
4
│   ├── role: "user"
5
│   ├── content: string | Content[]
6
│   └── timestamp: number
7
│
8
├── AssistantMessage ⭐（message_update中最常见）
9
│   ├── role: "assistant"
10
│   ├── content: ContentPart[]  ← 多种内容块
11
│   │   ├── TextContent { type: "text", text }
12
│   │   ├── ThinkingContent { type: "thinking", thinking }
13
│   │   └── ToolCall { type: "toolCall", id, name, arguments }
14
│   ├── usage: Usage            ← token统计
15
│   ├── stopReason: StopReason  ← 结束原因
16
│   └── timestamp: number
17
│
18
└── ToolResultMessage
19
    ├── role: "toolResult"
20
    ├── toolCallId: string      ← 对应的ToolCall.id
21
    ├── content: Content[]
22
    ├── isError: boolean        ← 执行是否失败
23
    └── timestamp: number

message_update 中的实际类型：流式响应期间，message 通常是 AssistantMessage，正在累积 content 数组。

关联二：AssistantMessageEvent 类型树#

13种底层事件，每种都携带 partial: AssistantMessage（当前累积状态）：

1
AssistantMessageEvent（13种）
2
│
3
├── start
4
│   ├── type: "start"
5
│   └── partial: AssistantMessage
6
│
7
├── text_delta ⭐（最常用）
8
│   ├── type: "text_delta"
9
│   ├── contentIndex: number   ← content数组的索引
10
│   ├── delta: string          ← 增量文本
11
│   └── partial: AssistantMessage
12
│
13
├── text_end
14
│   ├── type: "text_end"
15
│   ├── contentIndex: number
16
│   ├── content: string        ← 完整文本
17
│   └── partial: AssistantMessage
18
│
19
├── toolcall_start
20
│   ├── type: "toolcall_start"
21
│   ├── contentIndex: number
22
│   └── partial: AssistantMessage
23
│
24
├── toolcall_delta
25
│   ├── type: "toolcall_delta"
26
│   ├── contentIndex: number
27
│   ├── delta: string          ← JSON片段
28
│   └── partial: AssistantMessage
29
│
30
├── toolcall_end ⭐（常用）
31
│   ├── type: "toolcall_end"
32
│   ├── contentIndex: number
33
│   ├── toolCall: ToolCall     ← 完整工具调用对象
34
│   └── partial: AssistantMessage
35
│
36
├── thinking_delta
37
│   ├── type: "thinking_delta"
38
│   ├── contentIndex: number
39
│   ├── delta: string          ← 思考增量
40
│   └── partial: AssistantMessage
41
│
42
├── done
43
│   ├── type: "done"
44
│   ├── reason: "stop" | "length" | "toolUse"
45
│   └── message: AssistantMessage
46
│
47
└── error ⭐（错误处理）
48
    ├── type: "error"
49
    ├── reason: "aborted" | "error"
50
    ├── error: AssistantMessage
51
    └── (无partial，因为流已终止)

关键理解：

contentIndex：指示正在更新 content 数组的哪个元素
delta：增量字符串，每次新增的部分
content：完整字符串，块结束时的结果
partial：持续更新的累积状态（除 error 外）

类型复用关系#

多个类型在不同位置共享：

类型	出现位置	说明
AssistantMessage	message, partial, done, error	核心消息类型，多处使用
ToolCall	content[], toolcall_end.toolCall	工具调用定义，两处共享
Usage	AssistantMessage.usage	Token统计
StopReason	AssistantMessage.stopReason, done.reason, error.reason	结束原因
Content[]	UserMessage, AssistantMessage, ToolResultMessage	内容块数组

实际访问示例#

访问高层累积状态#

获取当前消息的累积内容、模型信息、token用量：

1
agent.subscribe((event) => {
2
  if (event.type !== "message_update") return;
3

4
  const currentMessage = event.message;
5

6
  if (currentMessage.role === "assistant") {
7
    console.log("累积内容块:", currentMessage.content.length);
8
    console.log("当前model:", currentMessage.model);
9

10
    // 查看第一个文本块（如果已生成）
11
    if (currentMessage.content[0]?.type === "text") {
12
      console.log("文本长度:", currentMessage.content[0].text.length);
13
    }
14
  }
15
});

访问底层事件细节#

根据底层事件类型分发处理：

1
agent.subscribe((event) => {
2
  if (event.type !== "message_update") return;
3

4
  const e = event.assistantMessageEvent;
5

6
  switch (e.type) {
7
    case "text_delta":
8
      // 实时文本增量
9
      process.stdout.write(e.delta);
10
      console.log("块索引:", e.contentIndex);
11
      break;
12

13
    case "toolcall_end":
14
      // 工具调用参数完整
15
      console.log("工具:", e.toolCall.name);
16
      console.log("参数:", e.toolCall.arguments);
17
      break;
18

19
    case "thinking_delta":
20
      // 思考过程（可选显示）
21
      console.log("[思考]", e.delta);
22
      break;
23

24
    case "error":
25
      // 错误处理
26
      console.log("错误:", e.reason);
27
      console.log("信息:", e.error.errorMessage);
28
      break;
29
  }
30
});

通过 partial 查看累积过程#

partial 字段持续更新，可用于预览生成过程：

1
agent.subscribe((event) => {
2
  if (event.type !== "message_update") return;
3

4
  const e = event.assistantMessageEvent;
5

6
  // 文本增量时，查看已生成的完整内容
7
  if (e.type === "text_delta") {
8
    const textBlock = e.partial.content[e.contentIndex];
9
    if (textBlock?.type === "text") {
10
      console.log("已生成:", textBlock.text);  // 包含之前的 + 新delta
11
    }
12
  }
13

14
  // 工具调用增量时，查看参数累积过程
15
  if (e.type === "toolcall_delta") {
16
    const toolBlock = e.partial.content[e.contentIndex];
17
    if (toolBlock?.type === "toolCall") {
18
      console.log("参数累积:", toolBlock.arguments);  // 不完整JSON
19
    }
20
  }
21
});

message vs partial 的区别#

两者通常指向同一个对象，但有细微差别：

字段	类型	来源	说明
message	AgentMessage	pi-agent-core	Agent层面的消息状态
partial	AssistantMessage	pi-ai	API层面的累积状态

实际使用：

流式响应中，两者通常是同一个 AssistantMessage 对象
message 是 Agent 维度的统一接口（可能是 User/Assistant/ToolResult）
partial 仅限于 AssistantMessage，是 API 层的累积状态

推荐：需要累积状态时，优先用 e.partial，因为类型更明确。

音乐

音乐