🎯 今日核心问题

  1. 什么情况下 Agent 会永远停不下来?列出至少三种真实发生过的死循环模式。
  2. 步数上限设多少合适?为什么说"能跑通"和"能上线"是两件事?
  3. 除了步数和 token,还有哪些"软性"信号说明该收手了?

📖 精读提纲

【一】三种终止路径

自然终止:模型返回的消息里没有 tool_calls(finish_reason=stop)。这是唯一"正常"的结束方式,占 90%。

硬终止:步数超限。MAX_STEPS 通常设 5-10,简单任务 5 够,多步规划任务 10-15。超过就直接返回兜底话术,不要静默返回空串,要告诉用户"信息不足"。

预算终止:累计 token 超阈值。一个 Agent 任务建议设 30k-50k token 上限(含所有轮次累加),超过就中止。因为消息链每轮都全量重发,token 消耗是 O(n²) 增长的——第 8 轮请求要把前 7 轮全部重发一次。这是 Agent 账单失控的头号原因。

【二】四种真实的死循环模式

1)重复调用同一工具同一参数。工具返回 {"error":"city not found"},模型不知道为什么失败,又用同样参数试一次,循环往复。检测方法:对 (toolName, arguments) 做哈希,同一哈希出现 2 次就直接中断并把错误回灌为"该参数已失败两次,请换方案或直接回答用户"。

2)参数抖动。每次微调参数("杭州"→"杭州市"→"浙江杭州")看起来不重复,实际毫无进展。检测方法:同一工具名连续调用 3 次仍未成功,强制中止。

3)工具返回过大导致上下文溢出。返回 500KB 的日志,下一轮直接 400 context_length_exceeded。这里必须在 Act 阶段做返回体截断:单条 tool 消息 content 建议上限 4k 字符,超出部分记"(已截断,共 N 字符)"。

4)两个工具互相甩锅。查订单说"请查物流",查物流说"请查订单"。检测方法:记录工具调用序列,出现 A→B→A→B 的循环模式即中止。

【三】实战应用:Spring Boot 场景——把终止条件做成独立组件

不要在 Service 的 for 循环里散落各种 if。抽出一个 StopCondition 接口,多个实现组合判断:MaxStepsCondition、TokenBudgetCondition、DuplicateCallCondition、NoProgressCondition。每轮循环结束前调 evaluate(context),返回 Optional<StopReason>。

好处是每个条件都能单测,而且终止原因可以随响应一起返回(stopReason=DUPLICATE_CALL),线上按原因聚合监控,你会立刻看出是哪个工具在拖后腿。另外 token 计数不要用模型返回的 usage 累加估算——那是精确值,直接取 usage.total_tokens 相加即可,别自己字符数除以 4。

还有一个工程细节:兜底话术要分场景。步数超限说"这个问题需要更多信息,请补充城市名";重复失败说"天气服务暂时不可用";预算超限说"任务过于复杂,已暂停"。千篇一律的"出错了"会让用户以为系统挂了。

【四】常见误区

💻 代码示例

public sealed interface StopReason
        permits MaxSteps, TokenBudget, DuplicateCall, LengthTruncated {
    record MaxSteps(int steps) implements StopReason {}
    record TokenBudget(int used) implements StopReason {}
    record DuplicateCall(String tool, String args) implements StopReason {}
    record LengthTruncated() implements StopReason {}
}

@Component
public class StopGuard {
    private static final int MAX_STEPS = 8;
    private static final int TOKEN_BUDGET = 40_000;
    private static final int TOOL_CONTENT_LIMIT = 4_000;

    private int tokenUsed = 0;
    private final Map<String, Integer> callCount = new HashMap<>();

    /** 每轮 Think 之后调用;返回 empty 表示可继续 */
    public Optional<StopReason> afterThink(int step, JsonNode choice) {
        tokenUsed += choice.path("usage").path("total_tokens").asInt(0);
        if ("length".equals(choice.path("finish_reason").asText())) {
            return Optional.of(new StopReason.LengthTruncated());
        }
        if (step >= MAX_STEPS) return Optional.of(new StopReason.MaxSteps(step));
        if (tokenUsed > TOKEN_BUDGET) return Optional.of(new StopReason.TokenBudget(tokenUsed));
        return Optional.empty();
    }

    /** 每个 tool_call 执行前调用:同一 (name,args) 第二次即判死循环 */
    public Optional<StopReason> beforeAct(String tool, JsonNode args) {
        String key = tool + "#" + args.toString();
        int n = callCount.merge(key, 1, Integer::sum);
        return n > 1 ? Optional.of(new StopReason.DuplicateCall(tool, args.toString()))
                     : Optional.empty();
    }

    /** Act 阶段:截断超大返回,防止撑爆下一轮上下文 */
    public static String truncate(String raw) {
        return raw.length() <= TOOL_CONTENT_LIMIT ? raw
             : raw.substring(0, TOOL_CONTENT_LIMIT) + "...(已截断,共" + raw.length() + "字符)";
    }

    public static String fallback(StopReason r) {
        return switch (r) {
            case StopReason.MaxSteps s    -> "该问题需要更多信息,请补充城市或日期后重试。";
            case StopReason.TokenBudget t -> "任务过于复杂,已暂停。建议拆分后提问。";
            case StopReason.DuplicateCall d -> "工具 " + d.tool() + " 连续失败,请换个问法。";
            case StopReason.LengthTruncated l -> "回答被截断,请缩小问题范围。";
        };   // sealed interface + switch 模式匹配,漏一个分支编译不过
    }
}

✏️ 今日动手

  1. 把 StopGuard 接进 LoopAgentService:Think 后调 afterThink,每个 tool_call 执行前调 beforeAct,工具返回统一过 truncate。
  2. 跑三个实验并记录 stopReason:① 正常问题(应为自然结束)② 重复问同一个不存在的城市(应触发 DuplicateCall)③ 把 MAX_STEPS 临时改成 1(应触发 MaxSteps)。
  3. 给 StopGuard 写 3 个 JUnit 测试,重点测 token 累加和重复检测的边界(第一次不拦、第二次拦)。

交付物:能打印出三种不同 stopReason 的日志,外加 README 里一张"终止策略"小表。

🔖 明日预告

条件都齐了,但真出问题时你依然只能看到"答案不对"。明天解决可观测性:把整条消息链、每轮的 token、每次工具调用的入参出参完整打出来,做成可读的日志格式,并给出一个"消息链快照"工具,让你能用肉眼重构出 Agent 每一轮的决策。