Message 与 Tool 的时序关系#

工具调用分为两个阶段：

阶段一：LLM 生成参数（message_* 事件） 阶段二：Agent 执行工具（tool_execution_* 事件）

message_end 的 stopReason=“toolUse” 是两者的边界。

为什么分两阶段？#

用具体场景说明：用户问”北京天气”，AI 调用工具查询。

LLM 只负责”说”要调用什么工具——生成工具名称和参数。 Agent 才负责实际”执行”工具函数——调用代码，获取结果。

这个分离是职责边界：

LLM 是生成者（生成调用意图）
Agent 是执行者（执行调用动作）

完整时序图#

1
用户输入: "北京今天天气怎么样"
2
│
3
│
4
├── turn_start                    ← 开始本轮对话
5
│
6
├── message_start                 ← LLM 开始生成
7
│   │   message: AssistantMessage（初始空状态）
8
│
9
├── message_update (多次)         ← 流式生成工具调用参数
10
│   │   assistantMessageEvent: toolcall_start
11
│   │   assistantMessageEvent: toolcall_delta '{"query"'
12
│   │   assistantMessageEvent: toolcall_delta ': "北京天气"'
13
│   │   assistantMessageEvent: toolcall_end
14
│   │       → toolCall完整: { id: "tc1", name: "search", arguments: { query: "北京天气" } }
15
│
16
├── message_end                   ← 参数生成完成
17
│   │   message.content[0]: ToolCall { name: "search", ... }
18
│   │   stopReason: "toolUse"     ← 关键：表示需要执行工具
19
│
20
│   ─────────── 阶段边界 ───────────
21
│   LLM 完成 → Agent 开始执行
22
│   ─────────── 阶段边界 ───────────
23
│
24
├── tool_execution_start          ← Agent 执行工具
25
│   │   toolCallId: "tc1"
26
│   │   toolName: "search"
27
│   │   args: { query: "北京天气" }
28
│
29
├── tool_execution_end            ← 工具执行完成
30
│   │   result: "北京晴天，25°C"
31
│   │   isError: false
32
│
33
├── turn_end                      ← 本轮结束
34
│   │   toolResults: [工具结果消息]
35
│
36
│   ─────── Agent 用结果继续生成 ───────
37
│
38
├── turn_start（新一轮）
39
├── message_start
40
├── message_update (text_delta)
41
├── message_end                   ← stopReason = "stop"
42
├── turn_end
43
│
44
└── agent_end                     ← 所有消息汇总

时序关键点：

message_end 之后才有 tool_execution（阶段边界）
tool_execution_end 之后可能触发新一轮 turn（用结果继续生成）
agent_end 是最终汇总点

两阶段监听协作#

一个完整的工具调用监听，展示两阶段如何衔接：

1
agent.subscribe((event) => {
2
  // ===== 阶段一：LLM生成参数 =====
3
  if (event.type === "message_update") {
4
    const e = event.assistantMessageEvent;
5

6
    if (e.type === "toolcall_start") {
7
      console.log("[LLM] 开始生成:", e.contentIndex);
8
    }
9

10
    if (e.type === "toolcall_delta") {
11
      // 参数JSON片段，如 '{"query": "天气"'
12
      console.log("[LLM] 参数增量:", e.delta);
13
    }
14

15
    if (e.type === "toolcall_end") {
16
      // 参数完整，即将进入阶段二
17
      console.log("[LLM] 参数完整:", e.toolCall.arguments);
18
      console.log("─── 阶段边界 ───");
19
    }
20
  }
21

22
  if (event.type === "message_end") {
23
    // stopReason = "toolUse" 表示即将执行工具
24
    if (event.message.stopReason === "toolUse") {
25
      console.log("[边界] LLM完成，Agent开始执行");
26
    }
27
  }
28

29
  // ===== 阶段二：Agent执行工具 =====
30
  if (event.type === "tool_execution_start") {
31
    console.log("[Agent] 执行:", event.toolName);
32
  }
33

34
  if (event.type === "tool_execution_end") {
35
    console.log("[Agent] 结果:", event.result);
36
  }
37
});

阶段边界判断：

message_end.stopReason === "toolUse" → 即将执行工具
tool_execution_start → 开始执行
tool_execution_end → 执行完成

一个 message 可能包含多个工具调用#

LLM 可以在一次响应中生成多个工具调用，Agent 会并行执行：

1
message_update:
2
  toolcall_end (contentIndex=0) → 工具 A: search
3
  toolcall_end (contentIndex=1) → 工具 B: translate
4
  toolcall_end (contentIndex=2) → 工具 C: summarize
5

6
message_end:
7
  message.content = [ToolCall_A, ToolCall_B, ToolCall_C]
8
  stopReason = "toolUse"
9

10
────────────────── 然后并行执行 ──────────────────
11

12
tool_execution_start → 工具 A 开始
13
tool_execution_start → 工具 B 开始
14
tool_execution_start → 工具 C 开始
15

16
tool_execution_end   → 工具 A 完成
17
tool_execution_end   → 工具 B 完成
18
tool_execution_end   → 工具 C 完成
19

20
turn_end:
21
  toolResults = [结果_A, 结果_B, 结果_C]

监听时，通过 contentIndex 区分不同的工具调用：

1
agent.subscribe((event) => {
2
  if (event.type === "message_update") {
3
    const e = event.assistantMessageEvent;
4

5
    if (e.type === "toolcall_end") {
6
      console.log(`[工具${e.contentIndex}] ${e.toolCall.name}`);
7
    }
8
  }
9

10
  if (event.type === "tool_execution_start") {
11
    console.log(`[执行] ${event.toolName} (${event.toolCallId})`);
12
  }
13
});

选择指南：监听哪层？#

需求	监听哪层	具体事件
显示”正在生成工具调用…”	底层	message_update + toolcall_start
显示参数生成过程（预览）	底层	message_update + toolcall_delta
显示”正在执行工具…”	高层	tool_execution_start
获取工具执行结果	高层	tool_execution_end
判断本轮是否有工具调用	高层	turn_end.toolResults.length
处理工具执行错误	高层	tool_execution_end.isError

原则：

需要实时预览参数生成过程 → 监听底层（toolcall_*）
其他情况 → 优先用高层（tool_execution_*）

音乐

音乐