智能体防超时要管整轮执行预算

Agent 连续调用工具，每次都成功，整轮任务却可能在平台强制截止时消失，连已经完成的结果也来不及交付。作者提出的办法是：把超时控制从单次调用提升到整轮执行，让每一步和重试共享预算，并提前留出保存状态、返回结果的时间。

这套思路适合需要多步工具调用的 AI 编程流程。它最有价值的地方，是把「突然中断」变成「明确交付部分成果」。不过，原文的时间算例存在一处错误，工程经验和验证结论也需要分开看。

每次调用都没超时，整轮为什么还会丢？

作者描述过这样的故障：Agent 前 40 次工具调用都很快，也都成功，但第 41 次碰到平台的整轮硬时限。代码没有收到异常，整轮执行及其结果就消失了。

单次调用超时只能限制某一次请求，管不了累计耗时。工具调用、重试等步骤如果各自计时，却不知道整轮还剩多少时间，就可能在局部正常的情况下耗尽总预算。

原文用「30 次调用，每次 8 秒，超过 300 秒」举例，但这里算错了：30 × 8 = 240 秒。除非还有超过 60 秒的其他开销，否则不能据此证明超时，而原文没有交代这些开销。这个错误不推翻预算思路，但该算例不能直接采用。

需要共享预算的是整轮执行，不能只给每次调用单独设闹钟。

作者给出的循环，在执行前判断下一步是否还能负担：

from turn_budget import TurnBudget

b = TurnBudget(total_s=280, reserve_s=20)   # 整轮预算 280 秒，保留 20 秒写出结果

for step in plan:
    if not b.can_afford(step.estimated_s):
        break                                # 交付已完成部分，说明未完成内容
    do(step)
    b.steps_run += 1

关键是 can_afford(step.estimated_s) 放在 do(step) 前面。按示例配置，280 秒中有 20 秒留给收尾；一个预计需要 30 秒的可选补充步骤，如果只剩 25 秒可用，就不再启动。

重试也必须服从同一预算。原文提出传入 budget_s=b.usable，防止重试循环继续花掉整轮已经没有的时间。仅在外层检查一次，内部重试却自行计时，预算仍然可能失控。

时间不够时，怎样交付才算有用？

预算耗尽后退出循环，只完成了一半工作。Agent 还得告诉调用方：完成了什么、跳过了什么，以及这次运行处于什么状态。

作者用下面的结果结构表达部分完成：

result = {
    "status":   "PARTIAL",          # 部分完成，不是成功，也不是失败
    "done":     b.steps_run,
    "skipped":  b.steps_skipped,
    "summary":  summary_of_completed_work,
}

要看的是 "status": "PARTIAL"。下游收到它，应把剩余步骤重新入队，而不是把整项任务标记为完成。相比在第 41 步消失，执行到第 37 步就主动交付，可以保住前 37 步的价值。这是原文的示意对比，不是收益统计。

步骤耗时怎么估？作者建议按步骤类型记录最近 N 次运行，用滚动观测数据估计；新类型先采用保守默认值。放行时参考观测到的 p95，也就是约 95% 的样本耗时不超过的值，而不是只看平均值。

原文同时提到滚动平均和 p95，但没有给出具体计算实现。可以确定的是，它主张用历史耗时约束决策，而不是要求开发者预知每一步的准确时间。

日志则记录预算对象的 summary()，包含已耗时、剩余时间、已执行和已跳过的步骤数，让「为什么只完成了一部分」有据可查。

我的判断

我认同「预算覆盖整轮、收尾提前预留、部分完成显式表达」这三个设计。它比单纯增加单次调用超时，更贴近多步 Agent 的失败方式；也比一味拉长平台时限，更有助于控制执行边界。

但执行前检查能否负担，不等于执行中一定不会超支。耗时估计可能失准，正在运行的步骤也可能拖住流程。原文强调每一步都应尊重预算，却没有展示 do(step) 如何接收剩余时间、如何取消正在运行的操作。因此，这段代码适合作为调度框架，不能直接视作完整的超时保障。

部分结果重新入队也有前提：系统需要保存进度，并能识别已经执行过的操作。原文提到了 checkpoint，却没有展开恢复逻辑。

作者称，这个模块来自 AgentOps Autopilot，采用 MIT 许可、仅依赖标准库，通过了 24/24 项测试，还做了注入真实整轮超时终止的混沌测试，并与 resilient_call、failure_journal 配合，把预算耗尽记为结构化失败记录。原文没有提供测试细节或对照数据，因此还不能据此判断它能降低多少故障率。

能拿来做什么

• 给多步 AI 编程任务设置整轮预算，把读取文件、执行工具和重试纳入同一套计时，并为保存状态和返回说明预留时间。
• 在 Node 编排层明确区分完整完成、PARTIAL 和失败，让调用方能够识别未完成步骤并安排续跑。
• 按工具或步骤类型记录耗时、剩余预算和跳过原因，再用观测到的 p95 调整放行判断，先从可选补充步骤开始控制成本。