Java Agent 工具调用的 allowlist、参数校验与调用预算
内容提要
文章以 Java 为例说明 Agent 工具调用必须由宿主程序控制：先设置工具白名单并默认拒绝，再校验参数格式与范围，最后限制调用次数等预算。模型只能建议调用，不能直接产生副作用。日志需记录拒绝原因，支付、删除等高风险操作应人工确认并使用幂等键。
延伸解读
三层校验缺一不可
文章强调工具调用需同时控制工具种类、参数和资源预算。只做白名单不验证参数，如允许get_order但不检查订单归属，仍可能泄露数据；只限制调用次数但允许delete_all同样危险。三层判断相互补充，任何一层缺失都会留下安全缺口。
常见错误与工程化日志
文章指出三类常见错误：把模型输出当可信JSON而不做schema验证；把“创建草稿”和“发送消息”共用同一工具；只记录成功调用而不记录拒绝原因。工程化应为每次决定保存工具、参数摘要、授权主体、规则版本、耗时和结果哈希，且日志不可写入完整敏感参数。
高风险操作需人工确认
涉及支付、删除、外发的工具应要求人类二次确认并使用幂等键。文章明确适用范围：适合客服助手、内部知识查询、代码审阅的只读工具与有人工确认的工作流；不适合让Agent自主执行转账、删库、发布生产配置。
Q&A
Java Agent 工具调用为什么必须由宿主程序控制？
因为函数调用只是模型提出工具与参数建议的协议，真正调用数据库、发货接口或邮件服务的权限仍在 Java 程序手里。模型永远不能越过宿主直接产生副作用。
Java Agent 工具调用的三层判断具体指什么？
第一层是工具种类：默认拒绝、按业务最小授权；第二层是参数：枚举、长度、正则、金额范围和权限主体逐项校验；第三层是资源预算：限制轮数、调用次数、并发和总耗时。
如何实现工具调用的默认拒绝和白名单？
在代码中定义允许的工具集合（如 Set.of("get_order", "create_reply_draft")），在授权函数中先检查调用次数是否超限，再检查工具名是否在白名单内，不在则返回拒绝。
参数校验应该包括哪些内容？
参数校验包括枚举、长度、正则、金额范围和权限主体逐项校验。例如订单号需匹配十位大写字母数字的正则，草稿文本不能为空且长度不超过500。
调用预算如何限制？
通过限制轮数、调用次数、并发和总耗时来实现。例如每轮最多两次工具调用，在授权函数中检查已用次数是否达到上限，达到则拒绝。
常见错误有哪些？
常见错误有三类：一，把模型输出当可信 JSON 而不进行 schema 验证；二，把“创建草稿”和“发送消息”共用同一工具；三，只记录成功调用而不记录拒绝原因。
高风险操作如支付、删除应如何处理？
涉及支付、删除、外发的工具应要求人类二次确认并使用幂等键。
日志记录应该包含哪些信息？
工程化应为每次决定保存工具、参数摘要、授权主体、规则版本、耗时和结果哈希；日志不可写入完整敏感参数。
