接缝、钩子与不可逆转的决定
智能体内核上的每一个钩子都能看见某些东西;只有一些能改变它,更少的能拒绝它。本章按每个钩子在触发时还能决定什么来映射它们,是测量得出的,而不是假设的。
第 1 章以一句话收尾,而从那以后它一直在悄悄地组织着这本书:
一个扩展点只有对那些它能在其变得不可逆转之前拦截下来的决定,才是一个真实的架构接缝。
在那里,它是作为一条关于编码智能体之分叉的发现被陈述出来的,并且是从三个案例论证出来的。本章在一样你能运行的东西上检验它。智能体内核有九个函数形状的选项,运行在一次请求或一次工具调用周围,而对每一个来说,有用的问题不是它给我什么,而是等它触发时我还能决定什么。
这九个
这些都是 Agent 上的选项,声明在 pi-agent-core 类型的 AgentOptions 里。README 记载了其中大部分;prepareNextTurn 和 prepareNextTurnWithContext 在声明里,而不在 README 的选项列表中。AgentOptions 里其他那些回调(streamFn、onPayload、onResponse、onProviderStreamEvent)观察或替换传输层,在这个意义上不是决策点。本章的第一个版本说的是七个,漏掉了 getApiKey 和第二种 prepareNextTurn 形式,这是一次独立评审抓住的。
| 钩子 | 接收什么 | 可以返回什么 |
|---|---|---|
prepareRequest |
上下文、模型、思考级别 | 一个替换用的上下文、模型或思考级别。没有否决字段 |
transformContext |
那些消息 | 替换用的消息 |
convertToLlm |
那些消息 | provider 格式的消息 |
beforeToolCall |
助手消息、那次工具调用、已校验的参数 | { block, reason, terminate }。没有参数替换字段 |
afterToolCall |
上面那些加上结果 | 替换用的 content、details、isError、structuredContent、usage、terminate |
finishTurn |
已结束的那一轮及其工具结果 | { action: "end" } 或 { action: "continue" } |
getApiKey |
provider 名字 | 一个凭据,或者什么都没有 |
prepareNextTurn |
只有一个中止信号,在 Agent 上 |
一个新的上下文、消息、模型或思考级别 |
prepareNextTurnWithContext |
已结束的那一轮(PrepareNextTurnContext)和一个信号 |
同样的更新 |
prepareNextTurn 那一行是要小心的那一行。裸循环的 AgentLoopConfig.prepareNextTurn 接收已结束的那一轮。在 Agent 上它不是:如果你需要那一轮,就用 prepareNextTurnWithContext。编码智能体在它编译后的源码里把两者桥接起来,而这就是这一点被发现的方式。
读了那张表,你会猜它们一样有用。它们不是,而原因不在表里。它在于每一个相对于它所关涉的那件事何时运行。
它们坐在哪里
用一轮调用工具的运行、在每个钩子上挂一个记录器,顺序就不再是一个见仁见智的问题。这是 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_execution_start 在 beforeToolCall 做出决定之前就被发出。那个事件说一个工具正在开始,即使对于闸门即将拦下的调用也是如此。README 说钩子运行在 tool_execution_start 和参数校验之后。记录器确认了这一点。一个在那个事件上画 “running…” 的 UI,会为被拒绝的调用也画出它来。
按每个钩子触发时已经发生了什么事来给这个序列分组。这个分组是关于时机的,而正是它决定了一个决定在哪里还便宜:
请求之前 prepareRequest、transformContext、convertToLlm
还没有向模型要过任何东西
效果之前 beforeToolCall
模型已经决定;什么都还没有运行
效果之后 afterToolCall、finishTurn、prepareNextTurn(WithContext)
工具已经运行;它的后果已经存在
这三个分组标题说的是已经发生了什么事,而不是一个钩子被允许做什么。一个钩子能否拒绝是一个有单独答案的单独问题,而两者必须分开:beforeToolCall 是唯一一个带有已声明拒绝能力的钩子,而那是因为它的声明返回类型,而不是因为它坐在哪里。一个会抛出的 prepareRequest 照样能拦住请求——上面那个标题是关于时机的陈述,而抛出是一种在协议之外行事的方式,而不是协议提供的一种能力。下面几节把两者分别给出。
那个分组就是整章的内容。下面的一切都是证据。
请求之前:你能改变模型看到的东西
transformContext 和 convertToLlm 改变被送出去的东西。它们不改变被保留下来的东西。那个测试发送两条用户消息,在 transformContext 里剥掉一条,然后问 provider 收到了什么:
送给 provider 的: 1 条用户消息
留在转录记录里的: 2 条用户消息
prepareRequest 也一样,它能为一次请求替换上下文、模型或思考级别。那个测试把一次调用里的 “cheap” 模型换成 “strong” 模型,而 provider 看到的是那个强的。
这里没有什么能被撤销,因为什么都还没有发生。一次从未发出的请求不花任何钱,也没有任何效果。这里是做决定最便宜的地方,而上下文策略就属于这里:修剪、摘要,以及按输入大小路由到一个模型。第 4 章的预算算术就是一个 transformContext 函数。
两个钩子都没有一个已声明的否决。PrepareRequest 返回一个 AgentRequestUpdate——上下文、模型、思考级别——而它里面没有任何一个字段意味着别把这个发出去。所以一个不希望请求发出去的钩子,没有一个有文档记载的方式来说出这件事,而表达那个决定的有支持的方式,是改变被发出去的东西。
要小心别把这一点推得太远。这是一个关于返回协议的陈述,而不是关于一个 JavaScript 回调能被逼着做什么的陈述。一个钩子就是你进程里的普通代码,而一个会抛出的回调不是一个有文档记载的返回值。
在 1.0.4 上观察:一个抛出 Error("blocked request") 的 prepareRequest 产生零次 provider 调用,而最终的助手记录带着 stopReason: "error"。这是行得通的,而对于一个你没预料到的请求来说,它是一种说得通的失败即关闭(fail closed)方式。它也不在类型里,所以它是已观察的,而不是有文档记载的:一个未来的版本完全可以给这个钩子一个已声明的拒绝能力,而一个今天会把抛出转换成失败轮次的实现,可能有一天不再这么做。对于一条你需要依赖的策略,优先选择有文档记载的那个面;而对于一个你宁愿其失败模式是可见错误、也不要是一次静默发送的守卫,抛出是一个合理的选择,恰恰因为它很吵。
效果之前:唯一一个能拒绝的点
beforeToolCall 是一个决定仍然可撤销的地方,而它是表中唯一一个能说不的钩子。它的结果类型有三个字段,block、reason 和 terminate:
const agent = new Agent({
initialState: { systemPrompt: "x", model, tools: [effectTool(counter)] },
streamFn: models.streamSimple.bind(models),
beforeToolCall: async ({ args }) => ((args as any).path === ".env" ? { block: true, reason: "protected path" } : undefined),
});
await agent.prompt("go");
assert.equal(counter.runs, 0);
counter.runs 是工具内部的一个副作用,所以 “was it run?” 是一个数字,而不是一次推断。它是 0。被拦下的调用作为一个带着原因的 isError 工具结果回来,而模型可以读到它并做出反应。那与第 16 章为编码智能体的 tool_call 事件记载的失效安全(fail-safe)结果相同,因为编码智能体正是建在这个钩子上的。它在内核的 Agent 上安装自己的 beforeToolCall。这在随附的 JavaScript 里是看得见的。它是已观察的,而不是有文档记载的,而你不应该把它当作契约来建立东西。
有一个限制会让写过扩展的人吃惊:内核的 BeforeToolCallResult 没有一个用于改写参数的字段。它有 block、reason 和 terminate,而那就是整个已声明的面。编码智能体的 tool_call 事件更宽松——一个处理器可以改动 event.input——但那是编码智能体自己的事件,不是内核的钩子,而本章讲的是内核。
再说一次,已声明的协议与这门语言的极限不是一回事,而这个区分值得保留,而不是把它抹平。在 1.0.4 上观察:一个改动 args.path 的 beforeToolCall 会让工具收到被改过的路径。编译后的循环把已校验的参数对象传给钩子,随后又把同一个对象传给工具,所以在 JavaScript 里一次改动是会落地的。
于是有三种立场,而诚实的排序是按你应该在多大程度上依赖每一种:
| 怎么改变一个工具收到的东西 | 在 1.0.4 上的状态 |
|---|---|
在工具内部,或在 AgentTool 上的 prepareArguments 里 |
有文档记载。 有支持的方式 |
在 beforeToolCall 内部改动 args |
已观察。 行得通,没有任何东西声明它,而它所倚靠的正是那个已校验参数的契约 |
BeforeToolCallResult 上的一个字段 |
不存在。 没有这样的字段;那部分是关于类型的一个陈述 |
用第一种。第二种值得知道,因为它解释了为什么一个扩展有时能做到比它的类型所承认的更多,也因为一个撞上它的读者应该知道,它倚靠的是一个实现细节,而不是在遵循一个契约。
效果之后:你能改写故事,不能改写世界
afterToolCall 能替换告诉模型的东西。它不能让工具没有运行过:
afterToolCall: async () => ({ content: [{ type: "text", text: "[redacted]" }], isError: true }),
counter.runs 1 那次写入已经发生了
模型看到的工具结果 "[redacted]",isError true
这就是本章之所以存在的那个区分。写入发生了。模型被告知了别的东西。如果那个效果是一个被写入的文件、一条被发出的消息或被删除的一行,那么没有更晚的钩子能把它收回来。afterToolCall 适合把输出里的一个密钥涂掉、把一种格式归一化,或者附上 usage。它对于任何你想用作预防的东西都是错的。
finishTurn 高一层具有同样的性质。它运行在助手消息和它所有工具结果都最终确定之后,而它可以返回 { action: "end" } 或 { action: "continue" }:
finishTurn 返回了 "end":
发出的请求: 1
工具运行次数: 1 已结束那一轮里的那个工具仍然运行了
它能让这次运行不再继续。它无法回头拦住已结束的那一轮所做的事。而一个无条件返回的 "continue" 是一个无限循环,README 对此有警告:finishTurn 在下一次请求之后又会运行。
接缝矩阵
前面那个分组,对照着"已经发生了什么"和"一个决定是否还可得"画出来。注意第四列:它是已声明的返回协议,而虚线箭头是语言允许的超过类型允许的地方。
flowchart TD
subgraph BEFORE["什么都还没有发生"]
PR["prepareRequest"] --> TC["transformContext"] --> CL["convertToLlm"]
end
CL --> REQ["provider 请求"]
REQ --> BTC["beforeToolCall"]
BTC --> EXEC["execute()"]
EXEC --> ATC["afterToolCall"]
ATC --> FT["finishTurn"]
FT --> PNT["prepareNextTurn(WithContext)"]
BTC -. "已声明:block、reason、terminate" .-> D1["唯一一个已声明的拒绝"]
PR -. "没有否决字段;一次抛出能拦住请求" .-> D2["已观察,未声明"]
BTC -. "没有 args 字段;改动 args.path 能落地" .-> D3["已观察,未声明"]
实线箭头是已声明的路径和已声明的决定权。虚线箭头是已观察但未声明的路径,而本章那些谨慎的限定就住在这里:它们在 1.0.4 上行得通,它们是真实的,而它们不是可以用来建立策略的东西。
| 钩子 | 何时触发 | 能观察 | 能转换 | 能拒绝 | 效果是否已发生 |
|---|---|---|---|---|---|
prepareRequest |
每次 provider 请求之前 | 能 | 上下文、模型、思考级别 | 没有否决字段 | 否 |
transformContext |
每次请求,转换之前 | 能 | 消息(送出但不存储) | 不能 | 否 |
convertToLlm |
每次请求 | 能 | 传输格式 | 不能 | 否 |
beforeToolCall |
调用被校验之后、execute() 之前 |
能 | 没有 args 字段 | 能 | 否 |
afterToolCall |
execute() 之后、结果被记录之前 |
能 | 那个结果 | 不能 | 是 |
finishTurn |
在这一轮的工具之后、turn_end 之前 |
能 | 不能 | 结束或继续 | 是 |
getApiKey |
在一次请求需要凭据之前 | 能 | 那个凭据 | 只有密钥:它无法拒绝请求 | 否 |
prepareNextTurn / …WithContext |
turn_end 之后、循环继续时 |
能 | 上下文、消息、模型 | 不能 | 是 |
把那两个带限定的单元格读作不存在的字段,而不是已被证明的不可能。上面两节给出了填满每个缺口的已观察行为,而 “no field for this” 与 “this cannot happen” 之间的区别,就是关于一个类型声明的陈述与关于一个运行程序的论断之间的区别。
这个矩阵大部分不是逐格测量出来的。examples/ch39-seams/ 里的八个测试测量的是:顺序、一次拦下能阻止效果、效果之后的一次改写不能撤销它、一次转换会被送出但不被存储、finishTurn 能结束或延长一次运行、prepareRequest 能换掉模型,以及 runToolCall() 会让一次嵌套调用穿过闸门。剩下的格子——包括 afterToolCall 和 finishTurn 在能拒绝和能转换下的每一个 “no”、getApiKey 和 prepareNextTurn 两行,以及 beforeToolCall 没有参数改写字段——都是对已声明结果类型的解读,而不是运行。一次独立评审发现早先的措辞(“every other cell has a test”)夸大了这一点。
读 “can refuse” 那一列时要带一个更正:拒绝是相对于一个具名决定的。对于 “may this effect happen” 这个决定,恰好有一个 “yes”,就是 beforeToolCall。对于 “does this run continue” 这个决定,返回 { action: "end" } 的 finishTurn 也是一种拒绝,agent.abort() 也是,还有引导和后续跟进队列也是——它们能让一次运行不结束。一个接缝是对一个决定而言的接缝,而本章的原则应该这样读。不改变的是效果那一列:每一个能拒绝这次运行的钩子,都是在工具的效果已经存在之后才这么做的。
所有能塑造模型的视野的钩子都坐在请求之前。唯一一个能拦住一个动作的钩子紧贴在它前面。之后的一切都是关于一件已经做完的事情的记账。
从一个决定到一层
现在这条规则可以当作一套流程来用。对于你想控制的任何决定,问最后一个可介入的时刻在哪里,然后把控制放在那里或更早。
| 这个决定 | 它能被拦下的最晚时刻 | 所以它属于 |
|---|---|---|
| 到底哪些工具可以存在 | 你构建 Agent 的时候 |
工具列表:最强的控制,第 42 章的第 0 级台阶 |
| 这次调用可以运行吗 | beforeToolCall |
一道读你自己拥有的表的闸门 |
| 模型从一次调用中看到什么 | afterToolCall |
一次结果改写,而效果已经发生 |
| 多少上下文,哪个模型 | prepareRequest / transformContext |
请求策略 |
| 是否还有下一轮 | finishTurn |
循环策略,在这一轮的效果之后 |
| 撤销一个工具做过的事 | 不在内核里 | 工具本身(把它做成事务性的)或一道操作系统边界 |
有一个字段让最后一行稍稍改变,而它值得知道。AgentTool.replay("never" | "safe")是工具所声明的 “recovery policy for an effect whose durable intent exists but whose outcome is unknown”。它不是一次撤销。它是工具对自身做出的一个陈述,而宿主的恢复逻辑将不得不信任它。一个由被约束的那一方选定的值,正是第 42 章警告过的那个模式,而在这里它坐在 Pi 自己的工具类型里面。
最后一行才是要紧的那一行。内核里没有一个钩子能撤销一个效果,因为等它们任何一个触发时,效果已经是工具自己的事了。一个即使在模型错了、闸门错了、工具也错了的情况下也必须成立的控制,必须住在效果所在的地方:在工具的设计里,或者在进程之下。第 42 章从这一行出发展开那个论证。
嵌套调用穿过同一道闸门
一个调用另一个工具的工具,不应该成为绕过你的闸门的一条路。内核导出 runToolCall() 正是为了这个:它的声明说它以 “the same steps as a model-issued call” 运行一次调用:“argument preparation, schema validation, beforeToolCall, execution, and afterToolCall",并且说调用其他工具的工具用它,“so the hooks (for example permission checks) apply to those calls too”。它从不因工具失败而拒绝。一次被拦下的或未知的调用会带着 isError: true 回来。
那是第 17 章为 ctx.executeTool() 记载的那个东西的内核版本。这一个是被运行的:examples/ch39-seams/ 里的一个测试带着一道 beforeToolCall 闸门,把一次指向受保护路径的调用通过 runToolCall() 传过去,而工具主体的计数器保持在零;一次被允许的调用运行一次;一个未知的工具以一个错误回来,而不是一次拒绝。如果你构建一个扇出到其他工具的工具,调用 runToolCall(),不要直接调用另一个工具的 execute(),否则你的闸门看不到那次嵌套调用。
映射到编码智能体
如果你写过扩展,这个对应关系紧到有用,又松到危险:
| 内核钩子 | 你认识的那个扩展事件 |
|---|---|
beforeToolCall |
tool_call(但扩展也可以改动 event.input) |
afterToolCall |
tool_result |
finishTurn |
turn_end 和返回 continue 的 agent_before_settle |
transformContext |
context |
本书提出,依据随附的源码与文档: 这些是同样的接缝,从两个层看到的样子。编码智能体添加了内核没有的事件(session_before_compact、project_trust、input),因为它拥有会话和项目,而那些恰恰是第 1 章说过扩展看得太晚的那些决定。不要把这张表读作对编码智能体如何实现的一种保证。
你能和不能论断什么
有文档记载: 这九个钩子及其结果类型(pi-agent-core README 与 types.d.ts,1.0.4),包括 beforeToolCall 运行在校验之后和 tool_execution_start 之后、terminate 的批次规则、finishTurn 上关于无限循环的警告,以及 runToolCall() 的契约。
已观察: 钩子顺序、拦下即阻止效果的行为、改写不撤销的行为、转换只送不存的行为,以及模型替换。全都在 examples/ch39-seams/ 里,在 1.0.4 上,在脚本化的响应下。编码智能体在内核上安装 beforeToolCall 和 finishTurn,这一点是在它编译后的 JavaScript 里观察到的。
本书提出: 请求之前、效果之前、效果之后这个分组、那张决定表,以及把预防放进工具里或进程之下的建议。
下一章
现在你知道能在哪里停下一步。你还没有做的是决定应该有多少步,或者其中哪些根本就不该是模型。第 36 到 38 章的零件(一次调用、一个循环、一个类型化步骤)可以组合起来,组合方式的花费差异极大,失败方式也差异极大。
第 40 章把它们组合起来。