AI Agent 任务超时怎么分层：模型超时、工具超时与总预算

线上Agent场景里最难排查的超时问题，往往不是单接口响应慢这么表面：大模型那边都已经返回结果了，调用的第三方工具还在长时间等待；工具调用刚结束没多久，整个任务却因为多轮来回推理把时间额度耗光了。经过实际验证比较可靠的方案，是把全链路等待时间拆成模型超时、单次工具超时和整条任务总预算三层，每一层触发终止时都能留存明确的触发原因。

先把三种“超时”分开看

一个标准Agent运行回合，一般是“模型决定下一步动作—调用对应工具—把工具返回结果再交回模型做判断”的循环流程。如果只在最外层套一个60秒的全局定时器，出问题之后日志里只会打印一句“任务超时”，你根本定位不到是大模型没响应、搜索类工具卡住，还是任务本身反复循环规划了太多轮把时间耗完了。

可以先定义三个时间边界：model_timeout限制单次模型请求，tool_timeout限制一次外部工具调用，task_deadline限制从任务接收至最终状态写入的总时长。三者不是并列的重试次数，而是嵌套的时间预算。

模型超时：只结束当前推理，不要误判整条任务

模型请求触发超时之后，首先要判断当前任务还剩多少可用时间。如果这次调用是幂等操作，运行过程中没有产生外部的副作用，剩余时间也足够支撑后续流程，就可以做一次带退避策略的重试；如果当前时间已经接近总截止线，再强行重试反而会导致最终的失败状态都没办法正常写入日志。

type Budget struct {
    Deadline    time.Time
    ModelLimit  time.Duration
    ToolLimit   time.Duration
}

func remaining(b Budget) time.Duration {
    return time.Until(b.Deadline)
}

func modelWindow(b Budget) time.Duration {
    left := remaining(b)
    if left 

这里的核心逻辑不是把硬编码的时间常量直接写到结构体里，而是每次发起模型请求之前，都重新计算一遍当前剩余的可用时间。比如上一轮工具调用已经消耗了12秒，下一次发起模型请求的时候，就不能还是直接给它分配完整的20秒额度。请求结束之后还要预留出结果序列化、更新任务状态和发送通知的时间。

工具超时：按调用边界切断，并保留证据

工具调用场景往往比模型请求更容易出现长尾耗时，比如数据库复杂查询、网页内容抓取或者企业内部的慢接口。每个工具都要配置自己的单独耗时上限，不能因为总预算还剩40秒，就放任某一个工具无限制地占用这部分时间。

工具超时后的状态建议至少包含 tool_name、call_id、started_at、elapsed_ms 和 reason=timeout。这些字段既能帮助排查，也能避免后续模型把“没有结果”误读成“工具返回了空结果”。

ctx, cancel := context.WithTimeout(parent, toolWindow)
defer cancel()

result, err := catalogLookup(ctx, query)
if err != nil {
    if errors.Is(ctx.Err(), context.DeadlineExceeded) {
        return ToolResult{Status: "timed_out", Retryable: true}
    }
    return ToolResult{Status: "failed", Retryable: classify(err)}
}
return ToolResult{Status: "completed", Data: result}

不要直接把超时结果转换成空数组或者空字符串传给后续逻辑。这种处理方式会让大模型基于不存在的空结果继续生成结论，最终出现“工具调用看起来成功、实际返回的答案完全偏离预期”的隐蔽错误，很难定位。

总预算：给规划和收尾留出不可抢占的时间

总时间预算的计时起点，要从任务进入队列的时候就开始算，不能等到第一条模型请求发出去才开始计时。预算消耗要覆盖模型请求、工具调用、重试执行、消息排队、结果整理和最终状态落库的全流程。实际工程落地的时候可以额外预留一小段收尾窗口，比如总预算是60秒的场景，最后3秒就不再启动任何新的外部调用，只做调用链取消传播和任务状态写入。

当剩余时间不足以完成一次完整的“模型请求加工具调用”闭环时，应该把任务标记为 deadline_exhausted，并返回已经收集到的可验证信息。不要为了追求“必须给出答案”继续开启第 N 轮，让任务在客户端已经断开后还占用资源。

重试与取消要遵守同一条时间线

重试策略至少要理清三个前提问题：这次失败后续有没有概率自动恢复、当前操作是不是幂等、重试执行完成之后有没有足够的时间写入任务终态。模型请求一般可以基于请求标识做有限次数的重试；带副作用的工具调用，必须先确认服务端的幂等约束，不能看到超时就直接盲目提交重试请求。

取消信号也要沿着整条调用链逐层传递。用户手动点了停止按钮、总预算耗尽或者上游连接断开的时候，都要先取消父级上下文，让当前正在运行的工具尽快释放占用的连接资源；等已经启动的清理动作执行完毕，再写入唯一的最终状态。重复收到取消信号的时候，不允许生成多条互相矛盾的任务结果。

上线前用四组场景验收

• 模型在单次时间窗口内超时：校验日志里只记录模型超时相关信息，工具调用状态不会被误标记为失败。
• 工具在单次时间窗口内超时：校验当前工具调用已经被取消，后续大模型收到的是明确的工具超时状态标识。
• 多轮调用耗尽总预算：校验系统不会再启动新的工具调用，任务最终状态可以正常写入存储。
• 用户主动触发取消：校验模型、工具和后续通知链路都能收到取消信号，日志里的调用序号完整不缺失。

验收超时逻辑的时候，最好同时统计任务耗时和状态转移链路，不能只看客户端有没有收到错误返回。一套真正可靠的超时实现，应该能清晰回答“哪个模块在什么时间点终止、触发终止的原因是什么、终止之后有没有残留副作用”这几个核心问题。

常见问题

模型超时后一定要重试吗？

不一定。先核对当前总预算剩余量、请求本身是否幂等、错误有没有可恢复的可能性。剩余可用时间不足的时候，直接记录模型超时并结束整个任务，通常比强行发起重试更稳妥。

工具超时能不能当成没有数据？

不能。超时代表没有在约定的时间窗口内拿到有效结果，不等同于工具返回了确认过的空结果。必须单独设置独立的超时状态，让上层逻辑自己判断后续要不要做回退或者重试操作。

为什么总预算还没到，仍然不能继续调用工具？

因为还要给模型回传数据、结果整理、取消信号传播和最终状态落库预留执行时间。剩余时间不足以跑完一个完整闭环的时候，继续发起调用只会增加悬挂任务和状态丢失的概率。

总结

Agent超时治理的核心不是设置一个更大的全局秒数，而是让模型调用、工具调用和整条任务的执行边界各自清晰。每次发起调用前都重新计算剩余预算，每次调用结束都明确记录终止原因，重试和取消操作沿着同一条时间线统一执行，才能把偶发的超时问题，变成可定位、可恢复、可验收的标准工程状态。