🎯 今日核心问题
- 模型选错工具时,Observation 长什么样?为什么它常常意识不到自己错了?
- 「工具返回空」和「工具返回错」的纠错策略为什么必须不同?
- 怎么区分「这个工具不该用」和「这个工具暂时失败」?
📖 精读提纲
【一】工具误用的四种形态与它们的信号
模型选错工具不是随机事件,它有稳定的几种形态,每种在 Observation 里留下的痕迹不一样:
- 语义近邻混淆:
queryOrderStatus和queryOrderDetail描述太像,选了后者,返回一大堆用不上的字段。信号:Observation 极长(>3000 字符)却没有目标字段。 - 粒度错配:要「近一年的营收」,调了
getLatestRevenue(只返回最新一期),得到单个数。信号:返回结构比预期少很多,但不是空的——这是最危险的,因为模型会拿这个数当答案。 - 参数拼错:调了正确的工具但参数名猜的,比如把
orderId写成orderNo。信号:400 + schema 报错。 - 选了不存在的工具:模型从训练数据里臆造了
search_web。信号:工具名查不到。
第一、二类最要命:没有异常,只有语义上的不匹配。你的 Java 代码无法靠 try-catch 抓住它们,必须主动做「结果校验」——这是今天最核心的工程点。
【二】Observation 要带上自描述与失败分类
很多人的工具返回是裸数据。应该改成带元信息的信封结构:
ok:是否成功(语义成功,不只是 HTTP 200)。errorType:PARAM_INVALID/NOT_FOUND/UPSTREAM_TIMEOUT/PERMISSION_DENIED/EMPTY。hint:给模型的下一步建议,这是纠错率提升最大的字段。比如「本工具只返回最新一期,查历史请用 queryRevenueHistory」。retryable:布尔。模型据此决定重试还是换路。
写 hint 的时候有个技巧:让工具作者自己写「你可能想用的是」。这比在 system prompt 里花 500 字解释工具区别有效得多,因为提示恰好出现在模型需要它的那一刻。
纠错策略要按 errorType 分流:PARAM_INVALID → 重试(把 schema 和报错一起回灌);NOT_FOUND → 换参数或换工具,不要重复太多次;UPSTREAM_TIMEOUT → 退避重试,超过 2 次降级;EMPTY → 大概率是选错工具或条件太窄,必须让模型重新评估工具选择。
【三】实战应用:Spring Boot 场景
场景:内部的「经营数据问答」Agent,工具集里有 queryRevenueHistory(按季度)、getLatestRevenue(最新一期)、queryRevenueByRegion(按大区分)。这三个工具的语义高度相邻,实测误用率约 25%。
三道防线:
- 工具描述去重:每个
@Tool的描述里都必须有一句「不适用于…」。这是成本最低的一招。 - 结果形状校验:在
ToolRegistry外面套一层ResultShapeGuard,给每个工具配一个期望形状(比如queryRevenueHistory期望返回 ≥2 条记录)。形状不符就返回EMPTY/MISMATCH+ hint,而不是把数据直接交给模型。 - 路径熔断:同一个工具连续失败 2 次,把它从本轮可用工具列表里临时摘除,强制模型换路。这一条能有效打断「死循环重试同一个错误工具」。
Spring Boot 实现上,用 ThreadLocal 或把 ToolCallStats 挂在 AgentContext 对象上(推荐后者,异步线程池里 ThreadLocal 会丢),记录 (toolName → 失败次数),每次构建 prompt 时过滤掉已被熔断的工具。
【四】常见误区
- ❌ 工具抛异常就返回
"error"。模型不知道是参数错还是网络错,只能瞎试。必须是分类错误码 + hint。 - ❌ 无限重试。同一个工具连续失败 2 次还没换路,基本就是选错了,再试只是烧钱。
- ❌ 靠 prompt 让模型「仔细选工具」。这只能提升几个百分点,真正的提升来自工具描述的互斥性和 hint 机制。
- ❌ 把「查不到」当错误吞掉返回空列表。模型会把空列表理解成「该维度数据为 0」,直接答错。要区分「no data」和「query failed」。
💻 代码示例
public record ToolResult(boolean ok, String errorType, String data,
String hint, boolean retryable) {
public static ToolResult ok(String data) { return new ToolResult(true, null, data, null, false); }
public static ToolResult fail(String type, String msg, String hint, boolean retryable) {
return new ToolResult(false, type, msg, hint, retryable);
}
public String toObservation() { // 回灌给模型的格式
if (ok) return "STATUS: OK\nDATA: " + data;
return "STATUS: " + errorType + "\nMESSAGE: " + data
+ "\nHINT: " + (hint == null ? "无" : hint)
+ "\nRETRYABLE: " + retryable;
}
}
@Component
public class ResultShapeGuard {
// 工具 → 期望的最小结果形状
private final Map<String, Predicate<JsonNode>> rules = Map.of(
"queryRevenueHistory", n -> n.isArray() && n.size() >= 2,
"getLatestRevenue", n -> n.has("period") && n.has("amount"),
"queryRevenueByRegion",n -> n.isArray() && n.size() >= 1
);
private final Map<String, String> hints = Map.of(
"getLatestRevenue", "本工具只返回最新一期。若要历史趋势,请用 queryRevenueHistory(quarters=N)。",
"queryRevenueHistory", "本工具不支持按大区拆分。要按大区请用 queryRevenueByRegion。"
);
public ToolResult guard(String toolName, String rawJson) {
JsonNode node;
try { node = new ObjectMapper().readTree(rawJson); }
catch (Exception e) { return ToolResult.fail("BAD_PAYLOAD", "工具返回非 JSON", "请联系工具维护者", false); }
Predicate<JsonNode> rule = rules.get(toolName);
if (rule != null && !rule.test(node)) {
return ToolResult.fail("SHAPE_MISMATCH",
"返回结构与工具契约不符: " + abbreviate(rawJson, 200),
hints.get(toolName), false);
}
return ToolResult.ok(rawJson);
}
}
@Service
public class ToolCallGuard {
private static final int BREAKER_THRESHOLD = 2;
public ToolResult invoke(AgentContext ctx, String toolName, String argsJson) {
if (ctx.failCount(toolName) >= BREAKER_THRESHOLD) {
return ToolResult.fail("TOOL_BREAKER_OPEN",
"该工具本轮已连续失败 " + ctx.failCount(toolName) + " 次,已被停用",
"请改用其他工具,或直接说明无法完成", false);
}
try {
String raw = ctx.registry().invoke(toolName, argsJson);
ToolResult r = new ResultShapeGuard().guard(toolName, raw);
if (!r.ok()) ctx.incFail(toolName);
return r;
} catch (IllegalArgumentException e) { // 工具名不存在 / 参数反序列化失败
return ToolResult.fail("PARAM_INVALID", e.getMessage(),
"请严格按工具 schema 传参,可用工具: " + ctx.availableTools(), true);
} catch (ResourceAccessException e) { // 上游超时
ctx.incFail(toolName);
return ToolResult.fail("UPSTREAM_TIMEOUT", e.getMessage(),
"可先跳过此步,稍后重试", true);
}
}
// 构建 prompt 时过滤掉熔断的工具
public List<String> availableFor(AgentContext ctx, List<String> all) {
return all.stream().filter(t -> ctx.failCount(t) < BREAKER_THRESHOLD).toList();
}
}
一次真实的误用与自纠正轨迹:
用户: 我们华东区今年前三季度营收趋势怎么样?
STEP 0
Thought: 需要华东区的营收数据,调 queryRevenueByRegion。
Action: queryRevenueByRegion {"region":"华东","period":"2026Q1-Q3"}
Observation: STATUS: SHAPE_MISMATCH
MESSAGE: 返回结构与工具契约不符: {"region":"华东","total":12.8}
HINT: 本工具不支持按季度拆分。要按季度请用 queryRevenueHistory 后按大区字段过滤。
RETRYABLE: false
STEP 1
Thought: 该工具只给汇总值,没有季度趋势。改用 queryRevenueHistory 拿季度序列再筛华东。
Action: queryRevenueHistory {"quarters":3}
Observation: STATUS: OK
DATA: [{"period":"2026Q1","region":"华东","amount":4.1}, ...共3条]
STEP 2
Thought: 三个季度数据齐全(4.1/4.4/4.3 亿),可以做趋势判断。
FinalAnswer: 华东区 2026 前三季度营收 4.1 → 4.4 → 4.3 亿元,Q2 环比 +7.3%,Q3 微降 2.3%,整体平稳。
对比一下没有 hint 的情况:模型看到 {"region":"华东","total":12.8} 完全可能直接回答「华东区前三季度营收 12.8 亿,缺乏明细」——一个语法正确但业务上不合格的答案。hint 那一行的成本几乎为零,却把这类失败从 25% 压到了个位数。
✏️ 今日动手
给现有工具集加 ToolResult 信封 + ResultShapeGuard + ToolCallGuard 熔断。要求:① 故意造两个语义相近的工具(比如 getLatestRevenue / queryRevenueHistory),跑 20 条测试问题统计误用率,加上 hint 后重跑同一批,把前后数字写进笔记;② 验证熔断:让某工具稳定抛超时,确认第 3 次调用时它已从可用列表消失,且模型会转向别的路径;③ 在 AgentContext 里记录每次工具调用的 {tool, errorType, round},这份数据下周做可靠性层时会直接用上。
🔖 明日预告
这周你的 Agent 已经能规划、能纠错、能自审了。但它对你来说是个黑盒——用户只看到最后一段文字。明天讲规划的可观测性:怎么把每一步的状态、耗时、token 暴露成前端能渲染的数据结构。