怎么说呢，

那个让我后背发凉的念头

catbuddy 的主要循环 AgentRunner 是个上千行的状态机——上一篇你已经见识过它有多忙：调模型、流式回吐、跑工具、处理截断、做重试。它是整个 harness 里改起来最让人手抖的一段代码。

有一天面试官问我「你是怎么评测 Agent 的？」我一脸懵逼，二面结束后我调研了相关框架，发现 Langfuse 是二开的最佳开源框架之一：

通过 Docker 自托管后我面临了一个痛点：「能不能给每次对话接上 Langfuse。把每一轮的 token 用量、工具调用链都记下来方便排查成本异常？」我的第一反应是——那我得在循环里、模型调用前后、工具执行前后分别插上埋点代码。

只是我立刻想象到了三个月后这段循环的模样：重试逻辑、Langfuse 埋点、未来某个项目要的脱敏逻辑，再来个调试插件…，全挤在同一个状态机里。每加一个需求都要改一次代码，每改一次都怕把已有功能踩坏。不过，这就是经典的「主要代码沦为意大利面」剧本。其实，

真正的问题不是「怎么接 Langfuse」而是： 怎么让所有这类「观察 + 副作用」需求。都能 Agent 的运行流程，却一行都不碰 AgentRunner？

catbuddy 的答案是一套 Hook 程序。说到主要一句话，

在 AgentRunner 一次迭代的关键节点上预先「开洞」。外部代码把自己的逻辑塞进洞里循环本身完全不知道，也不关心洞里插了什么。

九个生命周期插槽。长在循环的哪儿

AgentHook（位于 agent/hook.ts) 定义了九个生命周期方法,对应 Agent 一次迭代里九个「可以被观察 / 介入」的时刻。下面这张示意图把它们钉在 AgentRunner 循环中的真实位置上：

• 迭代两端：beforeIteration 与 afterIteration。
• 流式三连：onStreamemitReasoningemitReasoningEnd。
• 工具一钩：beforeExecuteTools。
li>收尾两钩：

This mapping is not a guess—open alert runner.ts and you can match each call one‑by‑one:

hook.beforeIteration;hook.beforeExecuteTools;按理说，hook.afterIteration;// ，etc.

The most important point:The default implementation of every method is a no‑op.

export class AgentHook {
constructor {}
wantsStreaming: boolean { return false } // 默认：不关心流式
async beforeIteration {} // 默认：什么都不做
async beforeExecuteTools {}
async afterIteration {}
// …其余方法同理，全是空实现
}

This means **zero overhead**. The runner always calls se methods;if you don’t plug any Hook y’re just empty functions that get inlined away by V8. You only override slots you care about;everything else stays “air”. This is foundation—default harmless,open on demand.

A subtle optimisation lives in : before invoking it runner checks wantsStreaming. Streaming callbacks fire at token‑level frequency,so if a Hook signals “I don’t need streaming” runner skips whole path。keeping hot loops fast.

HookContext：每个插槽都能看到整轮完整状态

The or half of a useful Hook is visibility. Every Hook method receives an AgentHookContext object that carries ** entire state of current iteration**:

interface AgentHookContext {
iteration: number;// 第几轮
messages: LLMMessage;// 完整对话历史
response?: {
content，toolCalls;usage，…
}，// 本轮 LLM 响应
说到usage，TokenUsage;怎么说呢，// 累计 token 消耗
toolCalls: ToolCallRequest;// 本轮要执行的工具调用
toolEvents: ToolEvent;// 全部工具事件历史
finalContent: string | null;// 最终回复
至于error，string | null;// 错误信息
}

If you need “token usage this turn” or “which tools were invoked”,y’re already in ctx.response?.usage and ctx.toolCalls / ctx.toolEvents . No need to dig into Runner internals.

Langfuse追踪：一个 Hook，零侵入

The real‑world requirement we introduced earlier can now be satisfied with **ten lines of code**:

class LangfuseHook extends AgentHook {
constructor { super;}
// 每轮 LLM 响应回来后：记一笔 token 用量 + 工具列表
override async afterIteration: Promise {
this.trace.span({
说到name。`iteration-${ctx.iteration}`,usage: ctx.response?.usage,// ← token账单直接拿到
tools的观点是。ctx.toolCalls.map,// ← 本轮使用了哪些工具
});}
}

You simply instantiate it and pass it via spec.hook when creating Runner. When runner reaches its internal call to hook.afterIteration your hook runs automatically—**no change to core loop**,no risk of breaking existing logic.

The diagram below shows a box labeled “不动” around Runner – that’s promise kept by Hook system.

A note on reality: catbuddy already ships a production‑ready version called LangfuseAgentHook that expands this pattern into a three‑layer trace tree . The next article will dive deep into that structure。cost estimation and PII masking.

CompositeHook：组合多个 Hook 且互不拖累

If you need more than one concern you can’t stick three objects into a single hook field. Enter CompositeHook :

• The composite itself implements AgentHook
• An internal array holds any number of child Hooks.
• The Runner still sees only one Hook instance.
• Error isolation is baked in – a failing non‑critical hook never brings down ors or main flow.

private async forEachHookSafe: Promise {
for {
try {
await hook;// 挨个调用子 Hook
} catch {
if throw err;//关键 Hook：异常向上冒泡
console.error;// 普通 Hook：吞掉异常，继续下一个 —— 不连累别人
}
}
}

The optional reraise flag lets you mark certain Hooks as “critical”. For example a state‑sync Hook that must succeed can be created with ).reraise = true;. By default all hooks are isolated – one bad apple won’t spoil whole basket.

从命名边界来看，Hook 是观察插槽，回调是数据管道

You might wonder *** catbuddy still has explicit callbacks like ,onReasoning,progressCallback . Those are used to push streaming tokens to UI – y are part of **data pipeline**. Hooks serve a different purpose.

	Hooks"	显式回调"
定位"	"站在循环边缘。看完状态再做副作用"	"直接搬运数据到外部程序"
干什么"	"观察内部状态 → 上报/记录/触发副作用"	"转换 / 搬运 数据 → UI / 下游服务"
谁用"	"框架层 / 子程序 / 第三方 "	"AgentRunner 的直接使用者 "

* 表格仅示意，两者职责泾渭分明，不混用。
• /推荐看看/把 Hooks 当作「轻量旁观者」← 它们只读上下文，不参与主流程；而回调则是 「主动推送」← 必须保持高性能与低延迟。<> / li>

空插座也是一种架构表达

The base / defines nine methods but many concrete subclasses only override two or three . The rest remain empty – are y redundant?Absolutely not.

• <="">: 在回复使用者之前对最终文本进行一次统一 比去修改 AgentRunner 安全百倍；它还是 CompositeHook 中唯一采用「管道模式」的方法——像 Express 中间件那样顺序传递修改结果。<> / li
• <="">: 每轮 LLM 调用前进行预算检查或安全校验，无需钻进循环内部治理代码。话说回来，<> / li
• <="">: 实时分析输出流。例如检测重复话术并提前中断。<> / li

An empty slot is a deliberate architectural signal saying “we anticipate future needs here”. New team members see those holes and instantly know *where* to plug ir logic instead of hunting through a monolithic state machine.

如果重来一次…

The current design intentionally makes Hooks **sequential and read‑only** – y observe n return control back to Runner. If we wanted Hooks to *intervene*,we’d have to redesign control flow,add conflict resolution 娱乐ween multiple Hooks,and decide how Agent should react when a tool is blocked. That extra power brings proportional complexity and risk.

This is *** today’s contract is deliberately narrow: **Only observe。never dictate**. It keeps extension surface simple and guarantees that adding new Hooks never puts core loop into an

要点

• AgentHookLangfuse_hook 即可组合多个关注点，并通过  实现错误隔离——单个失败不会拖垮其他插件或主流程。<>/ li
• <命名边界>观察 插槽，显式回调为数据管道。职责分离确保高频方法不受 逻辑拖慢。<>/ li
• <空 插座概念>

          

• - 完整链路结构如何搭建？
.
• - 成本估算与实时报警机制？
.
• - PII 脱敏策略及自托管部署细节？
. \end{itemize}