《Agent Runtime 工程化》给 Agent Loop 加 Max Iteration

工具调用要能生成 fingerprint：

function stableJson(value: unknown): string {
  if (value === null || typeof value !== "object") return JSON.stringify(value);
  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;

  return `{${Object.entries(value as Record<string, unknown>)
    .sort(([a], [b]) => a.localeCompare(b))
    .map(([key, val]) => `${JSON.stringify(key)}:${stableJson(val)}`)
    .join(",")}}`;
}

function toolFingerprint(call: ToolCall) {
  return `${call.name}:${stableJson(call.input)}`;
}

不要直接 JSON.stringify()。对象 key 顺序不稳定时，两个相同语义的输入可能生成不同字符串。

shouldStop 不要散落在 loop 里

停止判断最好集中成函数。

function shouldStopBeforeStep(state: RunState, maxSteps: number) {
  if (state.steps.length >= maxSteps) {
    return { stop: true as const, reason: "max_steps" as const };
  }

  if (state.sameErrorCount >= 3) {
    return { stop: true as const, reason: "repeated_error" as const };
  }

  for (const count of state.toolFingerprints.values()) {
    if (count >= 3) {
      return { stop: true as const, reason: "repeated_tool_call" as const };
    }
  }

  return { stop: false as const };
}

然后 loop 每一轮开始前先问它：

for (;;) {
  const decision = shouldStopBeforeStep(state, maxSteps);
  if (decision.stop) {
    state.stopReason = decision.reason;
    return state;
  }

  // build context
  // call model
  // execute tools
}

这比在 loop 里到处写 if 稳。后面加 token budget、用户取消、权限拒绝、run timeout，也都放进这个函数。

repeated_error 怎么算

最简单的算法：连续错误码相同，就累计。

function updateErrorCounter(state: RunState, results: ToolResult[]) {
  const errorResults = results.filter((r) => r.status === "error");

  if (errorResults.length === 0) {
    state.sameErrorCount = 0;
    return;
  }

  const firstCode = errorResults[0].errorCode ?? "UNKNOWN_ERROR";
  const allSame = errorResults.every((r) => (r.errorCode ?? "UNKNOWN_ERROR") === firstCode);

  state.sameErrorCount = allSame ? state.sameErrorCount + 1 : 1;
}

这只是入门版。

更好的实现会把工具名、错误码、关键参数一起算进去：

function errorFingerprint(result: ToolResult) {
  return `${result.toolName}:${result.errorCode ?? "UNKNOWN_ERROR"}`;
}

比如模型连续三次调用 read_file({ path: "src/foo.ts" })，都返回 NOT_FOUND，那就该停。

不要让模型继续猜。

repeated_tool_call 怎么算

每次执行工具前，记录 fingerprint：

function recordToolCall(state: RunState, call: ToolCall) {
  const fp = toolFingerprint(call);
  const count = state.toolFingerprints.get(fp) ?? 0;
  state.toolFingerprints.set(fp, count + 1);
}

如果同一个工具、同一组参数出现 3 次，通常说明 observation 没有给模型足够新信息，或者工具描述误导了模型。

这时候继续跑，意义不大。

停止后应该给用户一个能理解的解释：

我停止在第 6 步，因为连续 3 次调用 read_file(path="src/foo.ts") 都返回 NOT_FOUND。
建议先确认文件路径，或让我重新列出 src 目录。

这比'max iterations reached'好太多。

maxSteps 应该怎么设

不要上来就设 50。

不同任务应该有不同默认值：

问答 / 摘要：3-5 步
读代码定位入口：6-10 步
小型修复：10-15 步
跨文件重构：20+ 步，但必须有预算和 checkpoint

更重要的是，maxSteps 应该和成本、权限、checkpoint 一起看。

一个允许写文件、跑测试、联网、安装依赖的 Agent，maxSteps 不应该和只读巡检 Agent 一样。每多一步，都可能多一次工具副作用和一轮模型成本。

所以配置不要只写：

maxSteps: 20

至少写成：

type LoopBudget = {
  maxSteps: number;
  maxModelCalls: number;
  maxToolCalls: number;
  maxRunMs: number;
  maxRunTokens: number;
};

下一篇会专门讲 token budget。这里先记住：step 是成本单位，也是风险单位。

stop reason 要进入 trace

最小 trace 里应该记录：

{
  "runId": "run_123",
  "maxSteps": 8,
  "steps": [
    {
      "index": 1,
      "toolCalls": [
        {
          "name": "read_file",
          "fingerprint": "read_file:{\"path\":\"src/foo.ts\"}"
        }
      ],
      "toolResults": [
        {
          "status": "error",
          "errorCode": "NOT_FOUND"
        }
      ]
    }
  ],
  "finished": {
    "reason": "repeated_tool_call"
  }
}

这份 trace 不需要华丽。它要能回答三个问题：

模型为什么继续？
工具是否带来新信息？
runtime 为什么停止？

如果 trace 里只有聊天记录，max iteration 问题很难复盘。模型会解释得头头是道，但你要看的是系统事实。

eval 也要测停止条件

很多人写 eval，只测'最后回答对不对'。

Agent Runtime 还要测'有没有及时停'。

至少写几个 golden task：

case 1：fake model 一直调用 unknown_tool。
期望：runtime 以 repeated_error 停止。

case 2：fake model 三次读取同一个不存在文件。
期望：runtime 以 repeated_tool_call 或 repeated_error 停止。

case 3：fake model 直到 maxSteps 都不 final。
期望：runtime 以 max_steps 停止，step 数等于配置。

case 4：用户取消。
期望：runtime 以 user_cancelled 停止，不再调度新 tool。

本书 demo 的 eval harness 就不是靠最终回答完全一致来判定，而是看 tool ledger、required tools、forbidden tools、denied tool、最终回答包含的证据。

停止条件也应该进入这种行为断言。

UI 里不要只显示'失败'

对用户来说，停止不一定是失败。

permission_denied 可能是正常结果。budget_exhausted 可能是在保护成本。repeated_error 可能是在避免浪费时间。max_steps 可能表示任务需要拆小。

最终回答可以这样写：

我没有继续执行。

原因：连续三次读取 src/foo.ts 都返回 NOT_FOUND。

已完成：
- 列出了 src 目录。
- 读取了 src/index.ts。

建议：
- 确认目标文件名。
- 或允许我重新搜索相关函数。

这才像一个工具，而不是一个突然停摆的黑盒。

最后

给 Agent Loop 加 max iteration，不是为了让它'最多跑几步'。

是为了让它在失控前停下来，并且说清楚为什么停。

maxSteps 是保险丝。

stop reason 是诊断。

trace 是证据。

eval 是防止同样问题下次再回来。

这几个东西连起来，Agent Loop 才开始像 Runtime。

参考资料

• LangChain issue: "Agent stopped due to max iterations."
• LangChainJS issue: agent stuck in a loop
• LangFlow issue: Agent stopped due to max iterations
• LangGraph Docs: GRAPH_RECURSION_LIMIT
• n8n community: How to fix AI Agent stopped due to max iterations

推荐阅读

• Agent 为什么必须有 Token Budget？
• 给 Tool Call 加 Exponential Backoff Retry
• 为什么 Tool 必须支持 Idempotency？