Spring AI Alibaba 26｜Hooks 与 Interceptors · 自定义 Hooks 和 Interceptors：ModelInterceptor

拦截和修改模型请求和响应：

import com.alibaba.cloud.ai.graph.agent.interceptor.ModelInterceptor;
import com.alibaba.cloud.ai.graph.agent.interceptor.ModelRequest;
import com.alibaba.cloud.ai.graph.agent.interceptor.ModelResponse;
import com.alibaba.cloud.ai.graph.agent.interceptor.ModelCallHandler;

public class LoggingInterceptor extends ModelInterceptor {

  @Override
  public ModelResponse interceptModel(ModelRequest request, ModelCallHandler handler) {
      // 请求前记录
      System.out.println("发送请求到模型: " + request.getMessages().size() + " 条消息");

      long startTime = System.currentTimeMillis();

      // 执行实际调用
      ModelResponse response = handler.call(request);

      // 响应后记录
      long duration = System.currentTimeMillis() - startTime;
      System.out.println("模型响应耗时: " + duration + "ms");

      return response;
  }

  @Override
  public String getName() {
      return "LoggingInterceptor";
  }
}

动态工具管理：

ModelInterceptor 支持在模型调用前动态管理工具：

• dynamicToolCallbacks：动态添加工具回调，可以在运行时根据上下文添加新的工具
• tools：动态筛选工具，指定本次调用可用的工具名称列表。如果为空，则使用所有默认工具

import com.alibaba.cloud.ai.graph.agent.interceptor.ModelInterceptor;
import com.alibaba.cloud.ai.graph.agent.interceptor.ModelRequest;
import com.alibaba.cloud.ai.graph.agent.interceptor.ModelResponse;
import com.alibaba.cloud.ai.graph.agent.interceptor.ModelCallHandler;
import org.springframework.ai.tool.ToolCallback;
import org.springframework.ai.tool.function.FunctionToolCallback;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;

public class DynamicToolInterceptor extends ModelInterceptor {

  // 示例：根据上下文动态创建的工具
  private ToolCallback createContextualTool(String context) {
      return FunctionToolCallback.builder("contextual_tool", (String input) -> {
          return "处理上下文: " + context + ", 输入: " + input;
      })
      .description("根据上下文动态创建的工具")
      .build();
  }

  @Override
  public ModelResponse interceptModel(ModelRequest request, ModelCallHandler handler) {
      // 从上下文中获取信息，决定添加哪些工具
      Map<String, Object> context = request.getContext();
      String userRole = (String) context.getOrDefault("user_role", "default");

      // 构建修改后的请求
      ModelRequest.Builder builder = ModelRequest.builder(request);

      // 示例 1: 动态添加工具回调
      List<ToolCallback> dynamicTools = new ArrayList<>();
      if ("premium".equals(userRole)) {
          // 为高级用户添加额外工具
          dynamicTools.add(createContextualTool("premium_feature"));
      }
      builder.dynamicToolCallbacks(dynamicTools);

      // 示例 2: 动态筛选工具（只允许使用指定的工具）
      if (shouldRestrictTools(context)) {
          // 只允许使用 search 和 calculator 工具
          builder.tools(List.of("search", "calculator"));
      }
      // 如果 tools 为空列表，则使用所有默认工具

      ModelRequest modifiedRequest = builder.build();
      return handler.call(modifiedRequest);
  }

  private boolean shouldRestrictTools(Map<String, Object> context) {
      // 根据上下文决定是否限制工具
      return context.containsKey("restrict_tools");
  }

  @Override
  public String getName() {
      return "DynamicToolInterceptor";
  }
}

使用场景：

• 根据用户权限动态添加或移除工具；
• 根据对话上下文临时启用特定工具；
• 实现工具的动态加载和卸载；
• 在特定条件下限制可用的工具集。

拦截和修改工具调用：

import com.alibaba.cloud.ai.graph.agent.interceptor.ToolInterceptor;
import com.alibaba.cloud.ai.graph.agent.interceptor.ToolCallRequest;
import com.alibaba.cloud.ai.graph.agent.interceptor.ToolCallResponse;
import com.alibaba.cloud.ai.graph.agent.interceptor.ToolCallHandler;

public class ToolMonitoringInterceptor extends ToolInterceptor {

  @Override
  public ToolCallResponse interceptToolCall(ToolCallRequest request, ToolCallHandler handler) {
      String toolName = request.getToolName();
      long startTime = System.currentTimeMillis();

      System.out.println("执行工具: " + toolName);

      try {
          ToolCallResponse response = handler.call(request);

          long duration = System.currentTimeMillis() - startTime;
          System.out.println("工具 " + toolName + " 执行成功 (耗时: " + duration + "ms)");

          return response;
      } catch (Exception e) {
          long duration = System.currentTimeMillis() - startTime;
          System.err.println("工具 " + toolName + " 执行失败 (耗时: " + duration + "ms): " + e.getMessage());

          return ToolCallResponse.of(
              request.getToolCallId(),
              request.getToolName(),
              "工具执行失败: " + e.getMessage()
          );
      }
  }

  @Override
  public String getName() {
      return "ToolMonitoringInterceptor";
  }
}

本文整理自 Spring AI Alibaba 官方文档《Hooks 与 Interceptors》：https://java2ai.com/docs/frameworks/agent-framework/tutorials/hooks