🎯 今日核心问题
- 五个异构工具(DB / HTTP / 文件 / 计算 / 时间)怎么用同一套注册与执行机制装进一个 Agent?
- 哪些工具该给权限、哪些该限制参数范围,才能让它安全地"真的做事"?
- 本周的哪些能力可以直接写进简历与开源仓库的架构图?
📖 精读提纲
【一】五个工具,一套抽象
本周的五个工具覆盖了 Agent 最典型的四类副作用来源:数据源(queryOrders 走 Repository)、外部网络(getHttpJson 走 WebClient)、本地文件系统(readTextFile,必须做路径白名单与大小限制)、纯计算(calc,用脚本引擎并禁用反射)和系统时钟(now,带时区)。它们形态各异,但对外只需要一件事:@Tool 方法 + 统一 ToolResult 外壳。注册表负责发现与反射执行,执行器负责超时与异常转译,AgentService 负责多轮循环与并行批次——这四层就是本周的完整产出,也是下周做规划(Plan-and-Execute)时直接复用的底座。
值得强调的是权限分层:readTextFile 这类工具一旦暴露给模型,就等于把文件系统的一部分交给它,所以必须放在 admin 组、做路径规范化校验、限制文件大小;calc 和 now 无副作用,可以无条件给;queryOrders 要做用户隔离——模型给的 userId 不能直接信,应该用会话里的登录用户覆盖,否则一句"查一下 userId=2 的订单"就能越权。这条规则比任何 prompt 里写的"请不要越权"都可靠。
另一条经验是"工具越少越好"。本周五个工具已经接近单 Agent 的舒适区上限,如果继续加,就得按领域拆:订单 Agent、运维 Agent、报表 Agent 各自持有 3~5 个工具,用一个路由层决定交给谁。工具数量与选择准确率成反比,这不是模型能力问题,而是描述之间的语义重叠必然增加。
【二】写进简历的三件事
一是工具编排框架:注解驱动的自动注册、Schema 自动生成、按权限组过滤、反射绑定与超时隔离;二是可靠执行层:可自愈/不可自愈错误分类、同参重复检测、结构化错误回填;三是可观测性:每轮 tool_call 的耗时、token、命中率都有日志与指标。把这三块画成一张架构图放进 README,比写"熟悉 LangChain4j"有说服力得多。
【三】实战应用:把五个工具装进一个 Agent
工具类各自独立成 Bean,按 @Group 分权限;calc 与 now 无副作用归 default,queryOrders 归 data,readTextFile 归 admin,getHttpJson 限制在域名白名单内。提问示例:"帮我看看最近三笔订单总额,加上我本地 data/fee.txt 里的手续费,得出实付金额,并告诉我今天星期几"——这一句会触发 DB 查询、文件读取、计算、时间四个工具,是检验整条链路的最佳用例。整轮预期两到三轮:第一轮模型并行发起 queryOrders、readTextFile、now,第二轮拿到三个结果后调用 calc 做求和与加费,第三轮输出最终答复。如果模型把 calc 和查询放进同一轮,说明它猜了金额——这时要在 system 里补一句"涉及数值计算必须拿到具体金额后再计算",而不是改代码。
【四】常见误区
- ❌ 文件工具不做路径规范化——
../../etc/passwd一次就够穿。 - ❌ 计算工具用 JavaScript 引擎却不限制执行时长——死循环把线程挂死。
- ❌ 时间工具返回带时区的完整对象——模型只需要 ISO 字符串和星期几。
💻 代码示例
public record ToolResult<T>(boolean ok, String code, String message, T data) {
public static <T> ToolResult<T> ok(T d, String m) { return new ToolResult<>(true, "OK", m, d); }
public static ToolResult<Void> fail(String c, String m) { return new ToolResult<>(false, c, m, null); }
}
@Component
@RequiredArgsConstructor
@Group("data")
public class DbTools {
private final OrderRepository repo;
@Tool("查询某用户最近的订单,返回订单号、金额与状态。用户问我有几笔订单/最近买了什么时调用")
public ToolResult<List<OrderBrief>> queryOrders(
@P("用户ID,数字") Long userId,
@P("返回条数 1-20,默认3") Integer limit) {
int n = Math.min(limit == null ? 3 : limit, 20);
List<OrderBrief> rows = repo.findRecent(userId, PageRequest.of(0, n))
.stream().map(o -> new OrderBrief(o.getOrderNo(), o.getAmount().toPlainString(),
o.getStatusLabel())).toList();
return ToolResult.ok(rows, "查到 " + rows.size() + " 笔订单");
}
}
@Component
@RequiredArgsConstructor
public class HttpTools {
private final WebClient web; // 已配置 connect 1s / read 3s
@Tool("GET 一个 HTTP 接口并按 JSON 返回。仅允许白名单域名,用户要求调用外部 API 时使用")
public ToolResult<JsonNode> getHttpJson(@P("完整 URL,必须以 https:// 开头且在白名单内") String url) {
URI u = URI.create(url);
if (!Set.of("api.github.com", "api.exchangerate.host").contains(u.getHost()))
return ToolResult.fail("URL_NOT_ALLOWED", "域名不在白名单:" + u.getHost());
JsonNode body = web.get().uri(u).retrieve().bodyToMono(JsonNode.class).block();
return ToolResult.ok(body, "已获取 " + url);
}
}
@Component
@Group("admin")
public class FileTools {
private static final Path ROOT = Path.of("/data/agent").toAbsolutePath().normalize();
@Tool("读取文本文件内容(仅 /data/agent 下,最大 64KB),用户要求看某个文件内容时调用")
public ToolResult<String> readTextFile(@P("相对路径,如 data/fee.txt") String path) {
Path p = ROOT.resolve(path).normalize();
if (!p.startsWith(ROOT)) return ToolResult.fail("PATH_DENIED", "路径越界");
try {
if (Files.size(p) > 65536) return ToolResult.fail("FILE_TOO_LARGE", "文件超过 64KB");
return ToolResult.ok(Files.readString(p), "读取成功 " + path);
} catch (IOException e) {
return ToolResult.fail("FILE_ERROR", "读取失败:" + e.getClass().getSimpleName());
}
}
}
@Component
public class CalcTools {
private final ScriptEngine js = new ScriptEngineManager().getEngineByName("nashorn"); // JDK 8/11
@Tool("计算数学表达式,支持 + - * / % 与括号,用于金额、比例、总和计算")
public ToolResult<String> calc(@P("数学表达式,如 (99.00+120.50)*1.06") String expression) {
if (!expression.matches("[0-9+\\-*/(). %]+")) // 只放行数字与运算符
return ToolResult.fail("INVALID_EXPR", "表达式只允许数字和运算符");
try {
Object r = js.eval(expression);
return ToolResult.ok(((Number) r).doubleValue(),
expression + " = " + BigDecimal.valueOf(((Number) r).doubleValue())
.setScale(2, RoundingMode.HALF_UP));
} catch (Exception e) {
return ToolResult.fail("CALC_ERROR", "表达式无法计算:" + expression);
}
}
}
@Component
public class TimeTools {
@Tool("获取当前时间,可指定时区。用户问今天几号/星期几/现在几点时调用")
public ToolResult<Map<String, String>> now(
@P("时区,如 Asia/Shanghai,默认 Asia/Shanghai") String zone) {
ZoneId z = zone == null || zone.isBlank() ? ZoneId.of("Asia/Shanghai") : ZoneId.of(zone);
ZonedDateTime t = ZonedDateTime.now(z);
return ToolResult.ok(Map.of(
"iso", t.format(DateTimeFormatter.ISO_OFFSET_DATE_TIME),
"date", t.toLocalDate().toString(),
"weekday", t.getDayOfWeek().getDisplayName(TextStyle.FULL, Locale.CHINA)),
t.toLocalDate() + " " + t.getDayOfWeek().getDisplayName(TextStyle.FULL, Locale.CHINA));
}
}
再用一个不依赖脚本引擎的实现:JDK 17 上 Nashorn 已被移除,生产环境用这个更稳。
@Component
public class SafeCalcTools {
/** 递归下降解析:expr := term (('+'|'-') term)* ; term := factor (('*'|'/'|'%') factor)* */
@Tool("计算数学表达式,支持 + - * / % 与括号,用于金额、比例、总和计算")
public ToolResult<Double> calc(@P("数学表达式,如 (99.00+120.50)*1.06") String expression) {
try {
double v = new Parser(expression.replaceAll("\\s+", "")).expr();
return ToolResult.ok(BigDecimal.valueOf(v).setScale(2, RoundingMode.HALF_UP).doubleValue(),
expression + " = " + BigDecimal.valueOf(v).setScale(2, RoundingMode.HALF_UP));
} catch (RuntimeException e) {
return ToolResult.fail("CALC_ERROR", "表达式无法计算,请检查括号与运算符");
}
}
private static final class Parser {
private final String s; private int i;
Parser(String s) { this.s = s; }
double expr() { double v = term(); while (i < s.length() && (s.charAt(i)=='+'||s.charAt(i)=='-')) {
char op = s.charAt(i++); double r = term(); v = op=='+' ? v + r : v - r; } return v; }
double term() { double v = factor(); while (i < s.length() && "*/%".indexOf(s.charAt(i)) >= 0) {
char op = s.charAt(i++); double r = factor();
v = op=='*' ? v * r : op=='/' ? v / r : v % r; } return v; }
double factor() {
if (i < s.length() && s.charAt(i)=='(') { i++; double v = expr(); if (s.charAt(i++) != ')') throw new IllegalArgumentException(")"); return v; }
int st = i; while (i < s.length() && (Character.isDigit(s.charAt(i)) || s.charAt(i)=='.')) i++;
if (st == i) throw new IllegalArgumentException("number");
return Double.parseDouble(s.substring(st, i));
}
}
}
注册表按权限组把工具交给模型,admin 组只在登录用户具备权限时才加入:
@Bean
AgentAssistant assistant(DynamicToolRegistry reg) {
return AiServices.builder(AgentAssistant.class).chatModel(model)
.tools(reg.beansFor(Set.of("default", "data", "admin"))) // admin 按登录用户动态给
.build();
}
✏️ 今日动手
跑通完整用例:"帮我看看最近三笔订单总额,加上 /data/agent/data/fee.txt 里的手续费,算出实付金额,再告诉我今天星期几。" 记录轮数、每个工具耗时、总 token。再逐项做安全验证:用 ../../etc/passwd 触发 PATH_DENIED、用 while(1){} 触发表达式拦截、用非白名单 URL 触发 URL_NOT_ALLOWED。三项全拦住,本周产出即可收官并推送仓库。
🔖 明日预告
第3周进入多步推理与规划:工具已经有了,下一步是让 Agent 自己决定顺序。D1 讲 ReAct——推理与行动交替,为什么它比一次性规划更抗幻觉,以及最小可运行的 Thought/Action/Observation 循环。