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、一次工具调用
agent_start没有额外字段。turn_start没有额外字段。message_start/end{ message: userMessage };工具声明发生变化时还可能有 system message;prompt 是独立消息事件,不塞进agent_start。message_start/update*/endassistant message 流式生成;tool call 的生成事件嵌在 update 中。tool_execution_start{ toolCallId, toolName, args }。tool_execution_update*{ toolCallId, toolName, args, partialResult };只有工具报告增量时出现。tool_execution_end{ toolCallId, toolName, result, isError };失败仍叫 end,由isError区分。message_start/end{ message: toolResultMessage };执行结果成为模型可读消息。turn_end{ message: assistantMessage, toolResults };停止原因在message.stopReason内。turn_start→ … →turn_end模型读取 tool result,通常生成最终回答。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 · 课程地图
这一页,先记到这里。