第 6 章：Hooks 与 Interceptors，给 Agent 加检查站和切面

到现在为止，Agent 已经能回答、用工具、记忆、输出结构化结果。下一步是控制执行过程：模型调用前能不能整理消息？工具失败能不能重试？危险操作能不能先让人审批？这就是 Hooks 与 Interceptors 的舞台。

本章边界

本章只分清两个角色：Hook 什么时候用，Interceptor 什么时候用。权限、限流、审计、监控这些工程治理不会全塞进 Hook，后面工程化章节会继续展开。

1. 生活类比：机场安检和随行记录员

机场不是乘客从大门一路狂奔到登机口。中间有安检、验票、行李检查、登机广播。

Hooks 像固定检查站，站在流程里的某个位置，到了这里就必须经过。Interceptors 像随行记录员或 AOP 切面，包在一次模型调用或工具调用外面，记录、拦截、重试。

如果你熟悉 Spring，可以这样记：

概念	类比	更适合做什么
Hook	流程节点、检查站	改变流程、暂停、调整 state
Interceptor	AOP around advice	包装一次模型/工具调用，做日志、重试、保护栏
Observation	指标采集器	系统级可观测性

2. 最小示例

ModelHook loggingHook = new LoggingModelHook();
MessagesModelHook messageTrimmingHook = new MessageTrimmingHook();
ModelInterceptor guardrailInterceptor = new GuardrailInterceptor();
ToolInterceptor retryInterceptor = new RetryToolInterceptor();

ReactAgent agent = ReactAgent.builder()
        .name("my_agent")
        .model(chatModel)
        .hooks(loggingHook, messageTrimmingHook)
        .interceptors(guardrailInterceptor)
        .interceptors(retryInterceptor)
        .build();

这段代码可以翻译成一句话：

流程上加两个检查站，模型/工具调用外面再包两层保护。

3. Hook 和 Interceptor 的位置

这张图就是本章的重点。不要先背类名，先记住位置：

• Hook 是流程中的站点。
• Interceptor 是包在一次调用外面的壳。
• Human-in-the-loop 这类暂停恢复，通常要 Hook + Saver 配合。

4. 怎么选：决策表

需求	优先选择	原因
模型调用前整理消息	Hook	它在流程里，可以改 messages 或 state
模型调用次数限制	Hook	关注流程次数和执行位置
工具失败重试	ToolInterceptor	它包在工具调用外面，天然适合 retry
模型输入保护栏	ModelInterceptor	它包住模型调用，适合拦截、审计、降级
高风险工具人工审批	Hook + Saver	需要暂停、保存状态、恢复执行
记录调用耗时	Interceptor 或 Observation	只是横切指标，不必改流程

经验规则：

要改变流程，用 Hook。
要包住一次调用，用 Interceptor。
要看系统指标，用 Observation。

5. 新手容易误解什么

误解一：Hook 就是普通回调。

不是。Hook 会被放进执行链路，位置会影响流程。它不是随手一挂的小事件监听。

误解二：Interceptor 和 Hook 差不多。

不一样。Interceptor 更像 AOP，适合“围绕一次调用”做事，比如重试、日志、保护栏。

误解三：人工介入就是弹个确认框。

真正的人工介入要能暂停、保存状态、等待结果、继续执行。没有 Saver，就像让人签字但不保存表单，流程很快就失忆。

6. 本章小结

Hooks 和 Interceptors 的区别可以这样记：

Hook 改流程，Interceptor 包调用。

下一章我们正式走到框架底盘：Graph Core。

7. 练习题

1. 设计一个“模型最多调用 3 次”的 Hook，说清楚它需要读写哪些状态。
2. 设计一个“工具失败重试一次”的 ToolInterceptor，说清楚重试后仍失败怎么办。
3. 判断以下需求用 Hook 还是 Interceptor：敏感词拦截、工具超时、人工审批、记录耗时。

课后源码索引：想验证实现时再打开

你想验证的结论	源码锚点
官方 Hook / Interceptor 示例	examples/documentation/src/main/java/com/alibaba/cloud/ai/examples/documentation/framework/tutorials/HooksExample.java，类 HooksExample，方法 basicHooksAndInterceptors()、humanInTheLoop()、modelCallLimit()、toolRetry()、llmToolSelector()、contextEditing()
Hook 如何插入图	spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/ReactAgent.java，类 ReactAgent，方法 initGraph()、filterHooksByPosition(...)、setupHookEdges(...)、setupConditionalHookEdges(...)
Agent 级 Hook	spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/hook/AgentHook.java，类 AgentHook，方法 beforeAgent(...)、afterAgent(...)
模型级 Hook	spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/hook/ModelHook.java，类 ModelHook，方法 beforeModel(...)、afterModel(...)
模型拦截器	spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/interceptor/ModelInterceptor.java，类 ModelInterceptor，方法 interceptModel(...)
工具拦截器	spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/interceptor/ToolInterceptor.java，类 ToolInterceptor，方法 interceptToolCall(...)