Agent 事件顺序速查

区分模型生成流与工具执行事件,追踪一次 run 的完整生命周期。

本章目录CONTENTS ↓

本章以 Pi 1.1.0 的 2026-10-11 源码快照 为基准;实验性接口不代表长期兼容承诺。

先分清两件事:模型“生成一个 tool call”和 Agent“执行这个 tool call”不是同一层事件。

两层事件

pi-ai:生成流 start → toolcall_start → toolcall_delta* → toolcall_end → done。它们作为message_update.assistantMessageEvent被 Agent 向上转发。

pi-agent-core:执行生命周期 tool_execution_start → tool_execution_update* → tool_execution_end。这一层才会校验参数并调用tool.execute()。

一个 prompt、一次工具调用

  1. agent_start 没有额外字段。
  2. turn_start 没有额外字段。
  3. message_start/end { message: userMessage };工具声明发生变化时还可能有 system message;prompt 是独立消息事件,不塞进agent_start。
  4. message_start/update*/end assistant message 流式生成;tool call 的生成事件嵌在 update 中。
  5. tool_execution_start { toolCallId, toolName, args }。
  6. tool_execution_update* { toolCallId, toolName, args, partialResult };只有工具报告增量时出现。
  7. tool_execution_end { toolCallId, toolName, result, isError };失败仍叫 end,由isError区分。
  8. message_start/end { message: toolResultMessage };执行结果成为模型可读消息。
  9. turn_end { message: assistantMessage, toolResults };停止原因在message.stopReason内。
  10. turn_start→ … →turn_end 模型读取 tool result,通常生成最终回答。
  11. agent_end { messages };不是 summary,而且这里只是本次 loop invocation 产生的新消息。

精确 payload

事件 额外字段 常见误解
agent_start 无 不是{ message }
agent_end messages 不是{ summary }
turn_start 无 不是 tool call start
turn_end message, toolResults reason位于 assistant message
message_start message 系统、用户、助手、工具结果都可能出现
message_update message, assistantMessageEvent 只用于流式 assistant message
message_end message 它是状态写入的重要 barrier
tool_execution_start toolCallId, toolName, args 此时尚未完成 before hook
tool_execution_update toolCallId, toolName, args, partialResult 可出现零到多次
tool_execution_end toolCallId, toolName, result, isError 没有单独的 error 事件

run 何时结束?

不只是“没有 tool call”。正常路径还要确认没有待处理的 steering 和 follow-up;此外error、aborted、finishTurn 返回 { action: "end" },以及一整批结果都要求terminate时,也可能收口。

兼容测试提示 不要只断言最终文本。记录完整AgentEvent[],再断言事件类型顺序和各 payload 的关键字段。

第一手来源:agent/src/types.ts · agent-loop.ts · ai/src/types.ts · 课程地图

这一页,先记到这里。