一轮 Agent 的事件与工具流

沿执行轨迹走

1. 事件是可观察边界

   pi-agent-core 公开 agent_start/end、turn_start/end、message_start/update/end 和 tool_execution_start/update/end 等事件，UI 与宿主据此观察同一条运行链。

   [repo]

2. 工具批次的顺序语义

   默认模式先按顺序完成工具调用的预检，再并发执行允许的工具；完成事件按实际完成顺序发出，但写入上下文的 tool result 仍按模型原始调用顺序排列。任一工具声明 sequential 时，整批顺序执行。

   [repo]

3. 停止发生在明确边界

   工具结果通常触发下一次模型调用；工具结果可共同给出 terminate 提示，宿主也能在 turn 完成后用 shouldStopAfterTurn 结束循环。

   [repo]

每一步改变了什么

• 接入审计、取消或 UI 时，应监听事件和钩子，而不是从终端文本反推内部状态。

• 并发工具可能改变完成顺序；依赖前一步副作用的调用应显式选择顺序执行。

这条轨迹没有说明什么

• 事件顺序描述正常完成路径；Provider 错误、用户取消和 Extension 拦截会在相同边界产生不同终止结果。