Spring AI Alibaba 项目源码学习（十一）-Hook

Hook 机制分析

请关注微信公众号：阿呆-bot

概述

本文档分析 Spring AI Alibaba Agent Framework 中的 Hook（钩子）机制，包括 Hook 接口、AgentHook、ModelHook 的设计、实现原理、执行位置、跳转机制以及具体实现类。

入口类说明

Hook - 钩子接口

Hook 是所有钩子的基接口，定义了钩子的基本能力。

核心职责：

定义钩子名称
定义钩子类型
定义执行位置
定义跳转能力

关键代码：

public interface Hook {
	String getName();

	HookType getHookType();

	List<JumpTo> canJumpTo();

	/**
	 * Get the positions where this hook should be executed.
	 * By default, this method checks for the @HookPositions annotation on the implementing class.
	 *
	 * @return array of HookPosition values
	 */
	default HookPosition[] getHookPositions() {
		HookPositions annotation = this.getClass().getAnnotation(HookPositions.class);
		if (annotation != null) {
			return annotation.value();
		}
		// Default fallback based on hook type
		if (this instanceof AgentHook) {
			return new HookPosition[]{HookPosition.BEFORE_AGENT, HookPosition.AFTER_AGENT};
		} else if (this instanceof ModelHook) {
			return new HookPosition[]{HookPosition.BEFORE_MODEL, HookPosition.AFTER_MODEL};
		}
		return new HookPosition[0];
	}
}

HookPosition - 执行位置

HookPosition 枚举定义了钩子的执行位置。

关键代码：

public enum HookPosition {
	/**
	 * Hook executes before the agent starts processing
	 */
	BEFORE_AGENT,

	/**
	 * Hook executes after the agent completes processing
	 */
	AFTER_AGENT,

	/**
	 * Hook executes before the model is called
	 */
	BEFORE_MODEL,

	/**
	 * Hook executes after the model returns a response
	 */
	AFTER_MODEL
}

AgentHook - Agent 级别钩子

AgentHook 在 Agent 执行前后插入逻辑。

关键代码：

public interface AgentHook extends Hook {

    default CompletableFuture<Map<String, Object>> beforeAgent(OverAllState state, RunnableConfig config) {
        return CompletableFuture.completedFuture(Map.of());
    }

    default CompletableFuture<Map<String, Object>> afterAgent(OverAllState state, RunnableConfig config) {
        return CompletableFuture.completedFuture(Map.of());
    }

}

ModelHook - 模型级别钩子

ModelHook 在模型调用前后插入逻辑。

关键代码：

public interface ModelHook extends Hook {

    default CompletableFuture<Map<String, Object>> beforeModel(OverAllState state, RunnableConfig config) {
        return CompletableFuture.completedFuture(Map.of());
    }

    default CompletableFuture<Map<String, Object>> afterModel(OverAllState state, RunnableConfig config) {
        return CompletableFuture.completedFuture(Map.of());
    }

    @Override
    default HookType getHookType() {
        return HookType.MODEL;
    }
}

JumpTo - 跳转目标

JumpTo 枚举定义了钩子可以跳转的目标。

关键代码：

public enum JumpTo {
	tool,
	model,
	end
}

Hook 集成机制

Graph 集成

Hook 被集成到 ReactAgent 的 Graph 中：

关键代码：

// Add hook nodes
		for (Hook hook : hooks) {
			if (hook instanceof AgentHook agentHook) {
				graph.addNode(hook.getName() + ".before", agentHook::beforeAgent);
				graph.addNode(hook.getName() + ".after", agentHook::afterAgent);
			} else if (hook instanceof ModelHook modelHook) {
				graph.addNode(hook.getName() + ".beforeModel", modelHook::beforeModel);
				if (modelHook instanceof HumanInTheLoopHook humanInTheLoopHook) {
					graph.addNode(hook.getName() + ".afterModel", humanInTheLoopHook);
				} else {
					graph.addNode(hook.getName() + ".afterModel", modelHook::afterModel);
				}
			}
			else {
				throw new UnsupportedOperationException("Unsupported hook type: " + hook.getClass().getName());
			}
		}

		// Categorize hooks by position
		List<Hook> beforeAgentHooks = filterHooksByPosition(hooks, HookPosition.BEFORE_AGENT);
		List<Hook> afterAgentHooks = filterHooksByPosition(hooks, HookPosition.AFTER_AGENT);
		List<Hook> beforeModelHooks = filterHooksByPosition(hooks, HookPosition.BEFORE_MODEL);
		List<Hook> afterModelHooks = filterHooksByPosition(hooks, HookPosition.AFTER_MODEL);

		// Determine node flow
		String entryNode = determineEntryNode(beforeAgentHooks, beforeModelHooks);
		String loopEntryNode = determineLoopEntryNode(beforeModelHooks);
		String loopExitNode = determineLoopExitNode(afterModelHooks);
		String exitNode = determineExitNode(afterAgentHooks);

		// Set up edges
		graph.addEdge(START, entryNode);
		setupHookEdges(graph, beforeAgentHooks, afterAgentHooks, beforeModelHooks, afterModelHooks,
				entryNode, loopEntryNode, loopExitNode, exitNode, true, this);
		return graph;

工具注入机制

Hook 可以通过 ToolInjection 接口注入工具：

关键代码：

private void setupToolsForHooks(List<Hook> hooks, AgentToolNode toolNode) {
		if (hooks == null || hooks.isEmpty() || toolNode == null) {
			return;
		}

		List<ToolCallback> availableTools = toolNode.getToolCallbacks();
		if (availableTools == null || availableTools.isEmpty()) {
			return;
		}

		for (Hook hook : hooks) {
			if (hook instanceof ToolInjection) {
				ToolInjection toolInjection = (ToolInjection) hook;
				ToolCallback toolToInject = findToolForHook(toolInjection, availableTools);
				if (toolToInject != null) {
					toolInjection.injectTool(toolToInject);
				}
			}
		}
	}

具体实现

ModelCallLimitHook - 模型调用限制钩子

ModelCallLimitHook 限制模型调用次数，防止过度调用。

关键代码：

@HookPositions({HookPosition.BEFORE_MODEL, HookPosition.AFTER_MODEL})
public class ModelCallLimitHook implements ModelHook {

	private static final String THREAD_COUNT_KEY = "__model_call_limit_thread_count__";
	private static final String RUN_COUNT_KEY = "__model_call_limit_run_count__";

	private final Integer threadLimit;
	private final Integer runLimit;
	private final ExitBehavior exitBehavior;

	@Override
	public CompletableFuture<Map<String, Object>> beforeModel(OverAllState state, RunnableConfig config) {
		// Read current counts from state
		int threadModelCallCount = state.value(THREAD_COUNT_KEY, Integer.class).orElse(0);
		int runModelCallCount = state.value(RUN_COUNT_KEY, Integer.class).orElse(0);

		// Check if limits are already exceeded (before making the call)
		boolean threadLimitExceeded = threadLimit != null && threadModelCallCount >= threadLimit;
		boolean runLimitExceeded = runLimit != null && runModelCallCount >= runLimit;

		if (threadLimitExceeded || runLimitExceeded) {
			if (exitBehavior == ExitBehavior.ERROR) {
				throw new ModelCallLimitExceededException(...);
			}
			else if (exitBehavior == ExitBehavior.END) {
				// Add message indicating limit was exceeded and jump to end
				String message = buildLimitExceededMessage(...);
				List<Message> messages = new ArrayList<>((List<Message>) state.value("messages")
						.orElse(new ArrayList<>()));
				messages.add(new AssistantMessage(message));

				Map<String, Object> updates = new HashMap<>();
				updates.put("messages", messages);
				return CompletableFuture.completedFuture(updates);
			}
		}

		return CompletableFuture.completedFuture(Map.of());
	}

	@Override
	public CompletableFuture<Map<String, Object>> afterModel(OverAllState state, RunnableConfig config) {
		// Read current counts from state
		int threadModelCallCount = state.value(THREAD_COUNT_KEY, Integer.class).orElse(0);
		int runModelCallCount = state.value(RUN_COUNT_KEY, Integer.class).orElse(0);

		// Increment counters after the model call
		Map<String, Object> updates = new HashMap<>();
		updates.put(THREAD_COUNT_KEY, threadModelCallCount + 1);
		updates.put(RUN_COUNT_KEY, runModelCallCount + 1);
		return CompletableFuture.completedFuture(updates);
	}

功能：

跟踪线程级别和运行级别的模型调用次数
达到限制时终止 Agent 或抛出异常
支持跳转到 END

HumanInTheLoopHook

HumanInTheLoopHook 实现交互机制，允许人工干预 Agent 执行。

功能：

在模型调用后暂停执行
等待人工输入或确认
根据人工反馈决定继续或终止

PIIDetectionHook - PII 检测钩子

PIIDetectionHook 检测和处理个人身份信息（PII）。

功能：

检测消息中的 PII
标记或过滤敏感信息
保护用户隐私

关键类关系

以下 PlantUML 类图展示了 Hook 系统的类关系：

关键流程

以下 PlantUML 时序图展示了 Hook 的执行流程：

实现关键点说明

1. Graph 节点集成

Hook 被转换为 Graph 节点：

每个 Hook 方法对应一个节点
节点名称格式：{hookName}.{methodName}
通过边连接形成执行链

2. 位置分类

Hook 按位置分类：

BEFORE_AGENT：Agent 执行前
AFTER_AGENT：Agent 执行后
BEFORE_MODEL：模型调用前
AFTER_MODEL：模型调用后

3. 链式执行

Hook 按顺序链式执行：

beforeAgent hooks 按顺序执行
beforeModel hooks 按顺序执行
afterModel hooks 按逆序执行
afterAgent hooks 按逆序执行

4. 跳转机制

Hook 可以通过 canJumpTo() 定义跳转能力：

JumpTo.tool：跳转到工具节点
JumpTo.model：跳转到模型节点
JumpTo.end：跳转到结束节点

跳转通过状态中的 jump_to 键控制。

5. 工具注入

Hook 可以通过 ToolInjection 接口注入工具：

在 Graph 初始化时自动注入
支持按名称或类型匹配
用于 Hook 内部功能实现

6. 状态更新

Hook 通过返回 Map<String, Object> 更新状态：

返回的 Map 会合并到当前状态
支持键策略控制更新方式
可以修改消息、添加元数据等

总结说明

核心设计理念

生命周期钩子：在 Agent 和 Model 的关键生命周期点插入逻辑
Graph 集成：Hook 作为 Graph 节点集成到执行流程
跳转控制：支持灵活的流程控制，可以跳转到不同节点
工具注入：支持 Hook 使用工具实现复杂功能

关键优势

灵活性：可以在多个位置插入自定义逻辑
可扩展性：易于添加新的 Hook 实现
流程控制：支持跳转机制实现复杂流程
解耦设计：Hook 与核心逻辑解耦

解决的问题

监控和限制：通过 ModelCallLimitHook 限制调用次数
人工干预：通过 HumanInTheLoopHook 实现人工干预
安全检测：通过 PIIDetectionHook 检测敏感信息
工具集成：通过 ToolInjection 支持 Hook 使用工具

使用场景

ModelCallLimitHook：需要限制模型调用次数的场景
HumanInTheLoopHook：需要人工审核或确认的场景
PIIDetectionHook：需要保护用户隐私的场景
自定义 Hook：需要扩展 Agent 功能的场景

Hook 机制为 Agent Framework 提供了强大的扩展能力，使开发者能够在 Agent 生命周期的关键点插入自定义逻辑，实现复杂的业务需求。

posted @ 2025-11-18 19:53 wasp 阅读(2) 评论(0) 收藏举报

刷新页面返回顶部

wasp

自娱自乐

Spring AI Alibaba 项目源码学习（十一）-Hook

Hook 机制分析

概述

入口类说明

Hook - 钩子接口

HookPosition - 执行位置

AgentHook - Agent 级别钩子

ModelHook - 模型级别钩子

JumpTo - 跳转目标

Hook 集成机制

Graph 集成

工具注入机制

具体实现

ModelCallLimitHook - 模型调用限制钩子

HumanInTheLoopHook

PIIDetectionHook - PII 检测钩子

关键类关系

关键流程

实现关键点说明

1. Graph 节点集成

2. 位置分类

3. 链式执行

4. 跳转机制

5. 工具注入

6. 状态更新

总结说明

核心设计理念

关键优势

解决的问题

使用场景

公告