请求生命周期

了解钩子的顺序，才能选对钩子。每个阶段都会对所有扩展执行完毕，才进入下一阶段；扩展按 priority 升序运行（数值小的先执行）。

new request
     │
on_tool()       register the tools this request can call
     │
on_state()      restore history and inject system instructions
     │
on_message()    transform the pending user input
     │
append input
     │
before_run()
     │
turn 1..n       before_turn() → model step → tools → after_turn()
     │
after_run() → on_success() → RUN_COMPLETED

由于 on_tool 总是在 on_state 之前完成，提供 guidelines 的扩展可以描述每一个工具，无论它是哪个扩展注册的。优先级只改变同一阶段内部的顺序。

一个轮次

before_turn()
     │
before_model(context, request)      adjust context before this model call
     │
model streams deltas → final response
     │
after_model()
     │
     ├─ no tool calls ─▶ after_turn() ─▶ final answer
     │
     └─ tool calls ────▶ before_tool() ─▶ run tool ─▶ after_tool()
                                                            │
                                        after_turn() ◀───────┘
                                             │
                                        next turn

在任何钩子里都可以用 await context.emit(AgentEvent(...)) 发出 UI 进度，正在消费 Agent.stream() 的一方就能看到这个事件。

该用哪个钩子？

钩子	用途
on_tool	注册请求级工具。
on_state	恢复历史记录，并添加系统指令。
on_message	在用户输入发送出去之前改写它。
before_model	必须在模型调用前一刻改变的内容，包括压缩。
after_model	读取响应、用量，或记录检查点。
before_tool / after_tool	审批、改写或观察一次工具调用。
after_run / on_success	持久化结果并释放请求级状态。
on_error / RunCancelledEvent	在失败或取消之后做清理。

成功、失败与取消

清理需要覆盖这三条路径：

• 模型或钩子出错时会调用 on_error，并向上抛出原始异常。

• 取消请求会发布 RunCancelledEvent；on_error 和 on_success 都不会运行。

• 工具失败则不同：它会变成一条失败的工具结果，让模型能据此应对，而不是让整个请求失败。

所有钩子见生命周期钩子参考；能覆盖这三种情况的清理模式见状态、并发与清理。