《Agent Runtime 工程化》为什么你的 Agent Demo 永远上不了生产？

很多 demo 不写这些东西，因为写了不炫。可一旦上线，恰恰是这些东西救命。

Retry 最容易骗过工程师

重试看上去是可靠性手段，写起来也简单：

for (let i = 0; i < 3; i++) {
  try {
    return await tool.call(input);
  } catch (err) {
    await sleep(1000 * (i + 1));
  }
}

这段代码的问题是，它不知道自己在重试什么。

读文件失败了，重试大概率没事。创建订单失败了，重试就要小心。扣款、发券、发邮件、删除文件、提交 PR、执行数据库 migration，这些工具都带副作用。你不能只看异常类型，还要知道'上一次请求有没有被对方收到''副作用有没有发生''这一次 retry 和上一次是不是同一个业务意图'。

AWS Builders Library 专门写过一篇关于 idempotent APIs 和安全重试的文章。Stripe 的 API 文档也明确建议在创建或更新对象时使用 idempotency key，这样网络错误后可以用同一个 key 安全重试，避免创建第二个对象或执行两次更新。

把这个思想搬到 Agent Runtime 里，就是：工具调用不能只是函数调用。它至少要有一份账本。

type ToolLedgerEntry = {
  runId: string;
  stepId: string;
  toolName: string;
  inputHash: string;
  idempotencyKey?: string;
  status: "started" | "succeeded" | "failed" | "uncertain";
  sideEffect: "none" | "possible" | "committed";
};

当 create_order() 超时，runtime 不能只把 TIMEOUT 丢给模型。它要把这次调用标记成 SIDE_EFFECT_UNCERTAIN，接下来优先查订单状态，而不是直接再创建一次。

这个细节很土，但生产系统就靠这种土办法活着。

Max iteration 不是停止条件的全部

很多 Agent 框架会提供 maxIterations 或 maxSteps。这东西必须有，但它只是最后一道闸。

更好的 runtime 会记录停止原因：

type StopReason =
  | "final_answer"
  | "max_steps"
  | "max_tokens"
  | "timeout"
  | "permission_denied"
  | "repeated_tool_call"
  | "same_error_repeated"
  | "side_effect_uncertain";

这比一句'达到最大迭代次数'有用得多。

如果停止原因是 repeated_tool_call，你要查工具描述是不是误导了模型。如果是 same_error_repeated，你要看 observation 有没有给出可修复信息。如果是 max_tokens，问题可能在 Context Builder。如果是 permission_denied，最终回答应该告诉用户哪一步被拒绝，而不是装作什么都没发生。

我见过不少 demo 的循环长这样：

while not done:
  call model
  if tool_calls:
    call tools
  else:
    done

这不是不能用。它适合教学，适合视频演示，适合第一天证明'模型能调工具'。但它还缺少工程系统最关心的东西：

• 这一步为什么开始？
• 这一步用了哪些上下文？
• 工具调用是否合法？
• 工具结果有没有被截断？
• 有没有重复调用同一个高风险工具？
• 失败后是否应该让模型继续？
• 中断后能从哪里恢复？

这些问题没有答案，Agent Demo 就只能停留在 Demo。

聊天记录不是 Trace

很多团队第一次排查 Agent 问题，会先打开聊天记录。

聊天记录当然有用，但它不是 trace。它通常看不到 timeout、duration、token、工具输入摘要、权限决策、输出截断、artifact id、retry 次数，也看不到'模型为什么没看见某个文件'。

OpenTelemetry 对 trace、span、attribute、event 的划分已经很成熟。一个 span 表示一次有开始和结束的操作，attribute 记录键值信息，event 记录某个有时间点意义的事件。Agent Runtime 没必要重新发明可观测性，但需要把 Agent 专属事实记进去。

我会把一次 run 拆成这几类 span：

agent.run
  model.call
  context.build
  tool.call
  permission.decision
  checkpoint.save

每个 tool.call 至少记录：

{
  toolName: "create_order",
  inputHash: "sha256:...",
  status: "timeout",
  durationMs: 31200,
  sideEffect: "uncertain",
  retryCount: 1,
  idempotencyKey: "order:user_42:cart_998"
}

有了这个，你才知道事故怎么发生。没有它，复盘会变成猜谜。

第一版 Runtime 先做什么

如果你现在手里有一个 Agent Demo，别急着换框架，也别急着把 prompt 改得更长。先补六件事。

第一，定义统一消息结构。用户消息、模型消息、tool call、tool result 分清楚，不要靠字符串拼接糊在一起。

第二，写 Tool Registry。哪怕只有三个工具，也要有 schema、risk level、timeout、retry policy 和 output policy。

第三，所有工具返回结构化结果。失败不要只写 error: string，至少分出 INVALID_ARGUMENTS、NOT_FOUND、PERMISSION_DENIED、TIMEOUT、OUTPUT_TOO_LARGE、SIDE_EFFECT_UNCERTAIN。

第四，加停止原因。maxSteps 要有，但重复工具调用、重复错误、超时、预算耗尽、权限拒绝也要变成明确 stop reason。

第五，给有副作用的工具加 ledger 和 idempotency key。尤其是创建、更新、删除、支付、发消息、执行命令这类工具。

第六，写最小 trace。不要等接入完整观测平台才开始记录。先落 JSON 文件都行，只要能还原一次 run。

做到这里，你的系统未必已经是产品。但它已经不像玩具了。

真正的分水岭

我现在判断一个 Agent 项目有没有进入工程化，基本不看它 demo 视频多顺。

我看这些东西：

• 有没有 stop reason。
• 有没有 tool failure taxonomy。
• 有没有 permission decision。
• 有没有 context budget。
• 有没有 tool ledger。
• 有没有 checkpoint。
• 有没有 trace。
• 有没有 eval 能复现失败。

这些东西听上去没有'多智能体协作'酷，也没有'自动完成复杂任务'好卖。但一个 Agent 真到生产环境，最后天天救火的就是这些模块。

写 Agent Demo 是让模型动起来。

写 Agent Runtime 是让它出错时还能被控制。

我最近在把这套东西整理成《Agent Runtime 工程化》。后面会继续把架构图、代码样例、Production Checklist 和试读章节放出来。下一篇先讲一个最容易吵起来、也最值得讲清楚的问题：

Agent Loop、Harness、Runtime，到底是什么关系？

参考资料

• LangChain issue: "Agent stopped due to max iterations."
• LangChainJS issue: agent stuck in a loop
• LangFlow issue: Agent stopped due to max iterations
• OpenAI Docs: Function calling
• OpenAI Docs: Structured model outputs
• AWS Builders Library: Making retries safe with idempotent APIs
• Stripe Docs: Idempotent requests
• OpenTelemetry Docs: Traces

推荐阅读

• Agent Loop、Harness、Runtime 到底是什么关系？
• Agent 生产事故 #001：Retry 为什么会导致重复下单？
• 一次 Agent 任务为什么能烧掉几十次 LLM 调用？