Java Agent 工具调用的 allowlist、参数校验与调用预算

Agent 最危险的误解是“模型说要执行，所以系统就执行”。函数调用（Function Calling）只是一种让模型提出工具与参数建议的协议；真正调用数据库、发货接口或邮件服务的权限仍在你的 Java 程序手里。本文不绑定某一家 SDK，而是先实现所有 Agent 都该有的执行门：工具白名单、参数格式、次数预算和默认拒绝。它能在你接上 Gemini、其他模型或 MCP（Model Context Protocol，模型上下文协议）工具前先守住边界。

官方 Gemini API 文档将 Function Calling 描述为把 Agent 工作流连接到外部 API 的能力。关键架构是双回合：模型返回 function call 候选；宿主验证后执行；再把工具结果送回模型。模型永远不能越过宿主直接产生副作用。

运行前提

Java 17+ 即可，本例没有网络和密钥，因为安全门应能脱离模型独立测试。模型侧必须按官方 Function Calling 文档声明同名工具 schema；这里的 ToolCall 代表解析后的候选，而不是替代官方 API 请求。

javac AgentGate.java && java AgentGate

完整代码

代码只允许查询订单和创建草稿；拒绝取消订单等副作用工具。每轮最多两次工具调用，并把订单号限制为十位大写字母数字。execute 是可替换的受限适配器，真实实现中再接数据库或 HTTP 客户端，并分别设置连接与请求超时。

import java.util.*;
import java.util.regex.Pattern;

public class AgentGate {
  record ToolCall(String name, Map<String, String> args) {}
  static final Set<String> ALLOWED = Set.of("get_order", "create_reply_draft");
  static final Pattern ORDER = Pattern.compile("[A-Z0-9]{10}");
  static final int MAX_CALLS = 2;

  static String authorize(ToolCall call, int used) {
    if (used >= MAX_CALLS) return "DENY: 调用预算已用尽";
    if (!ALLOWED.contains(call.name())) return "DENY: 工具不在白名单";
    if (call.name().equals("get_order")) {
      String id = call.args().get("order_id");
      if (id == null || !ORDER.matcher(id).matches()) return "DENY: 非法订单号";
    }
    if (call.name().equals("create_reply_draft")) {
      String text = call.args().get("text");
      if (text == null || text.isBlank() || text.length() > 500) return "DENY: 草稿长度不合法";
    }
    return "ALLOW";
  }
  static String execute(ToolCall call) {
    return switch (call.name()) {
      case "get_order" -> "ORDER_FOUND: delivery=processing";
      case "create_reply_draft" -> "DRAFT_CREATED: no external message sent";
      default -> throw new IllegalArgumentException("unreachable");
    };
  }
  public static void main(String[] args) {
    List<ToolCall> suggestions = List.of(
        new ToolCall("get_order", Map.of("order_id", "AB12CD34EF")),
        new ToolCall("cancel_order", Map.of("order_id", "AB12CD34EF")),
        new ToolCall("create_reply_draft", Map.of("text", "您的订单正在处理中。")));
    int used = 0;
    for (ToolCall call : suggestions) {
      String verdict = authorize(call, used);
      if (verdict.equals("ALLOW")) { System.out.println(execute(call)); used++; }
      else System.out.println(verdict + " -> " + call.name());
    }
  }
}

预期输出先返回订单状态，再拒绝 cancel_order，最后仅创建一份草稿。这个次序说明：模型可以提出危险工具，但宿主拒绝不在白名单的名称。此次已用 javac AgentGate.java 编译并实际运行，输出符合预期；没有调用任何模型、数据库或线上工具。

不要跳过的三层判断

第一层是工具种类：默认拒绝、按业务最小授权；第二层是参数：枚举、长度、正则、金额范围和权限主体逐项校验；第三层是资源预算：限制轮数、调用次数、并发和总耗时。只做其中一层不够。例如允许 get_order 但不验证订单归属，仍可能泄露数据；限制两次调用但允许 delete_all 同样危险。

常见错误有三类：一，把模型输出当可信 JSON 而不进行 schema 验证；二，把“创建草稿”和“发送消息”共用同一工具；三，只记录成功调用而不记录拒绝原因。工程化应为每次决定保存工具、参数摘要、授权主体、规则版本、耗时和结果哈希；日志不可写入完整敏感参数。涉及支付、删除、外发的工具还应要求人类二次确认和幂等键。