按每个钩子还能决定什么来映射智能体内核的钩子
在 1.0.4 上记录内核钩子的顺序,并用接缝矩阵把拒绝、改写与观察区分开。
一个钩子只有在它触发时还能做出的那些决定上,才是一个真实的接缝。beforeToolCall 是唯一一个能拒绝一个效果的钩子;afterToolCall 改写故事,但不能撤销行为。本页重现 pi-agent-core 1.0.4 上那个观察到的顺序,然后是那个说出哪些决定在哪儿还便宜的接缝矩阵。
观察到的顺序
一次调用工具的运行,每个钩子上挂一个记录器——来自测试的那个精确断言:
assert.deepEqual(order, [
// turn 1: request preparation, then the provider call
"prepareRequest",
"transformContext",
"convertToLlm",
// the model asked for a tool; execution is announced before the gate runs
"tool.execute starts",
"beforeToolCall",
"afterToolCall",
"finishTurn",
"turn_end",
// turn 2: the same preparation, then the final answer
"prepareRequest",
"transformContext",
"convertToLlm",
"finishTurn",
"turn_end",
]);有两样东西不是你会猜到的:prepareRequest 运行在 transformContext 之前,而 tool.execute starts 在 beforeToolCall 决定之前就被宣告——一个在那个事件上画 “running…” 的 UI,也会为被拒绝的调用画出它来。按已经发生了什么事来给这个序列分组:
请求之前 prepareRequest、transformContext、convertToLlm
还没有向模型要过任何东西
效果之前 beforeToolCall
模型已经决定;什么都还没有运行
效果之后 afterToolCall、finishTurn、prepareNextTurn(...)
工具已经运行;它的后果已经存在每个钩子还能决定什么
那些被测量的行在 seams.test.ts 里是已观察的;而那些 “no” / 不存在字段的格子是对已声明结果类型的解读,不是运行。
| 钩子 | 运行时机 | 能转换 | 能拒绝 | 效果是否已发生 |
|---|---|---|---|---|
prepareRequest |
每次请求之前 | 上下文、模型、思考级别 | 没有否决字段 | 否 |
transformContext |
转换之前 | 消息(送出但不存储) | 不能 | 否 |
beforeToolCall |
校验之后、execute() 之前 |
没有 args 字段 | 能 | 否 |
afterToolCall |
execute() 之后 |
那个结果 | 不能 | 是 |
finishTurn |
在这一轮的工具之后 | 不能 | 结束或继续 | 是 |
那些被测量的情况:一次被拦下的调用让工具主体的计数器留在 0;一次改写仍然让计数器显示 1;一次转换送出一条用户消息,而转录记录保留两条;finishTurn 能停在一次请求,或强行来第二次;prepareRequest 为一次调用换掉模型;而一次通过 runToolCall() 的嵌套调用穿过同一道闸门,所以一次被拦下的永远不会执行。
机制与局限
有文档记载: 那九个 AgentOptions 钩子及其结果类型,beforeToolCall 运行在 tool_execution_start 和参数校验之后,terminate 的批次规则,以及 runToolCall() 的契约(pi-agent-core README 与 types.d.ts,1.0.4)。已观察: 那个顺序、拦下即阻止效果与改写不撤销的行为、转换只送不存的行为,以及模型替换。在 beforeToolCall 内部对 args 的一次改动在 1.0.4 上也会落地——它行得通,没有任何东西声明它,所以它不是可以用来建立策略的东西。本书提出: 那些钩子的分组,以及把预防放进工具内部或进程之下的建议。
不存在的字段不是已被证明的不可能;它们是关于类型的陈述。没有一个钩子能撤销一个效果,因为等任何一个钩子触发时,效果已经是工具自己的事了。这个示例在一个脚本化的 provider 下运行内核,所以它对于一个真实模型的工具选择什么也没说。
Understand this example
Copy this prompt into your AI tool. No code runs here.
Apply this example
Copy this prompt into your AI tool. No code runs here.