🎯 今日核心问题

  1. 模型选错工具时,Observation 长什么样?为什么它常常意识不到自己错了?
  2. 「工具返回空」和「工具返回错」的纠错策略为什么必须不同?
  3. 怎么区分「这个工具不该用」和「这个工具暂时失败」?

📖 精读提纲

【一】工具误用的四种形态与它们的信号

模型选错工具不是随机事件,它有稳定的几种形态,每种在 Observation 里留下的痕迹不一样:

第一、二类最要命:没有异常,只有语义上的不匹配。你的 Java 代码无法靠 try-catch 抓住它们,必须主动做「结果校验」——这是今天最核心的工程点。

【二】Observation 要带上自描述与失败分类

很多人的工具返回是裸数据。应该改成带元信息的信封结构:

写 hint 的时候有个技巧:让工具作者自己写「你可能想用的是」。这比在 system prompt 里花 500 字解释工具区别有效得多,因为提示恰好出现在模型需要它的那一刻。

纠错策略要按 errorType 分流:PARAM_INVALID → 重试(把 schema 和报错一起回灌);NOT_FOUND → 换参数或换工具,不要重复太多次;UPSTREAM_TIMEOUT → 退避重试,超过 2 次降级;EMPTY → 大概率是选错工具或条件太窄,必须让模型重新评估工具选择。

【三】实战应用:Spring Boot 场景

场景:内部的「经营数据问答」Agent,工具集里有 queryRevenueHistory(按季度)、getLatestRevenue(最新一期)、queryRevenueByRegion(按大区分)。这三个工具的语义高度相邻,实测误用率约 25%。

三道防线:

  1. 工具描述去重:每个 @Tool 的描述里都必须有一句「不适用于…」。这是成本最低的一招。
  2. 结果形状校验:在 ToolRegistry 外面套一层 ResultShapeGuard,给每个工具配一个期望形状(比如 queryRevenueHistory 期望返回 ≥2 条记录)。形状不符就返回 EMPTY/MISMATCH + hint,而不是把数据直接交给模型。
  3. 路径熔断:同一个工具连续失败 2 次,把它从本轮可用工具列表里临时摘除,强制模型换路。这一条能有效打断「死循环重试同一个错误工具」。

Spring Boot 实现上,用 ThreadLocal 或把 ToolCallStats 挂在 AgentContext 对象上(推荐后者,异步线程池里 ThreadLocal 会丢),记录 (toolName → 失败次数),每次构建 prompt 时过滤掉已被熔断的工具。

【四】常见误区

💻 代码示例

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 暴露成前端能渲染的数据结构。