AgentEvent 类型系统详解#

先看高层：AgentEvent（7 种业务事件）再看底层：AssistantMessageEvent（13 种技术事件）最后看关联：message_update 如何连接两者

高层：AgentEvent（7 种业务事件）#

AgentEvent 是应用层订阅的联合类型，包含 7 种事件。按语义边界分为四类：

事件分类总览#

类别	事件	核心字段	触发时机
生命周期	agent_start	无	Agent 初始化完成
	agent_end	messages[]	Agent 运行结束
Turn	turn_start	无	新一轮对话开始
	turn_end	message, toolResults[]	本轮对话结束
Message	message_start	message	LLM 开始响应
	message_update	message, assistantMessageEvent	流式更新（高频）
	message_end	message（含usage、stopReason）	LLM 响应完成
Tool	tool_execution_start	toolCallId, toolName, args	工具开始执行
	tool_execution_update	partialResult	工具执行中（可选）
	tool_execution_end	result, isError	工具执行完成

message_update 详解（最核心）#

message_update 是最复杂、最高频的事件：

1
{
2
  type: "message_update";
3
  message: AgentMessage;              // 当前累积状态
4
  assistantMessageEvent: AssistantMessageEvent;  // 底层事件（13种）
5
}

应用层通过这个事件：

访问累积的消息状态（message）
深入底层的流细节（assistantMessageEvent）
实现实时文本显示（text_delta）
处理 API 错误（error）

底层：AssistantMessageEvent（13 种技术事件）#

pi-ai 层的流式响应事件，描述 LLM 返回内容的逐步生成过程。

事件分类总览#

类别	事件	核心字段	含义
生命周期	start	partial	流开始
	done	reason, message	成功完成
	error	reason, error	出错终止
文本	text_start	contentIndex	开始文本块
	text_delta	delta	文本增量（最常用）
	text_end	content	文本完成
思考	thinking_start	contentIndex	开始思考块
	thinking_delta	delta	思考增量
	thinking_end	content	思考完成
工具调用	toolcall_start	contentIndex	开始工具调用
	toolcall_delta	delta（JSON片段）	参数增量
	toolcall_end	toolCall	参数完整

所有事件都携带 partial: AssistantMessage（当前累积状态）。

三种关键事件详解#

text_delta：实时文本增量（最常用）

1
{
2
  type: "text_delta";
3
  contentIndex: number;  // 内容块索引
4
  delta: string;         // 增量文本（如"根据"）
5
  partial: AssistantMessage;
6
}

用于实时显示 AI 回复的文本流。

toolcall_end：工具调用参数完整

1
{
2
  type: "toolcall_end";
3
  contentIndex: number;
4
  toolCall: {            // 完整的工具调用对象
5
    id: string;
6
    name: string;
7
    arguments: Record<string, any>;
8
  };
9
  partial: AssistantMessage;
10
}

用于判断工具调用参数已生成完毕，即将执行。

error：API 错误

1
{
2
  type: "error";
3
  reason: "aborted" | "error";
4
  error: AssistantMessage;  // 错误状态的消息
5
}

用于处理 API 调用失败或用户中止。

事件时序示例#

场景一：纯文本回复#

用户问：“你好”，AI 直接回复，无工具调用。

1
时间轴 →
2

3
agent_start
4
    │
5
    ↓
6
turn_start
7
    │
8
    ↓
9
message_start                 ← AgentEvent：LLM 开始响应
10
    │
11
    │  message_update (携带底层事件)
12
    │  ├── assistantMessageEvent: text_delta "你"
13
    │  ├── assistantMessageEvent: text_delta "好"
14
    │  └── assistantMessageEvent: text_delta "！"
15
    │      ↑ AssistantMessageEvent（高频触发）
16
    │
17
    ↓
18
message_end                   ← stopReason = "stop"
19
    │
20
    ↓
21
turn_end                      ← toolResults = []
22
    │
23
    ↓
24
agent_end                     ← messages: [用户消息, AI回复]

场景二：工具调用流程#

用户问：“北京天气”，AI 调用 search 工具查询，用结果继续回复。

1
时间轴 →
2

3
agent_start
4
    │
5
    ↓
6
turn_start（第1轮）
7
    │
8
    ↓
9
message_start
10
    │
11
    │  message_update
12
    │  ├── text_delta "我来查询"
13
    │  ├── toolcall_start (contentIndex=1)
14
    │  ├── toolcall_delta '{"query"'
15
    │  ├── toolcall_delta ': "北京天气"'
16
    │  ├── toolcall_end → toolCall完整
17
    │  │   └── toolCall: { id: "tc1", name: "search", arguments: { query: "北京天气" } }
18
    │  └── done → stopReason = "toolUse"
19
    │
20
    ↓
21
message_end                   ← stopReason = "toolUse"
22
    │
23
    │  ─────── LLM 完成，Agent 开始执行工具 ───────
24
    │
25
    ↓
26
tool_execution_start          ← toolCallId: "tc1", toolName: "search"
27
tool_execution_end            ← result: "北京晴天，25°C"
28
    │
29
    ↓
30
turn_end                      ← toolResults: [search的结果]
31
    │
32
    │  ─────── Agent 用工具结果继续生成 ───────
33
    │
34
    ↓
35
turn_start（第2轮）
36
    │
37
    ↓
38
message_start
39
    │
40
    │  message_update
41
    │  ├── text_delta "根据查询结果"
42
    │  ├── text_delta "北京今天晴天，25°C"
43
    │  └── done → stopReason = "stop"
44
    │
45
    ↓
46
message_end                   ← stopReason = "stop"
47
    │
48
    ↓
49
turn_end                      ← toolResults = []
50
    │
51
    ↓
52
agent_end                     ← messages: [用户, AI工具调用, 工具结果, AI回复]

时序关键点：

message_end 的 stopReason 决定是否执行工具
turn_end 后如果有工具结果，可能触发新一轮
agent_end 是最终汇总点，包含所有消息历史

音乐

音乐

AgentEvent 类型系统详解#

高层：AgentEvent（7 种业务事件）#

事件分类总览#

message_update 详解（最核心）#

底层：AssistantMessageEvent（13 种技术事件）#

事件分类总览#

三种关键事件详解#

事件时序示例#

场景一：纯文本回复#

场景二：工具调用流程#

支持与分享

音乐

文章目录