AI 应用如何处理工具调用超时：截止时间、取消信号与用户可见状态

AI 应用一旦让模型调用搜索、数据库或业务接口，最难处理的往往不是“工具能不能跑”，而是工具跑到一半超过了用户愿意等待的时间。只在外层 HTTP 请求上设一个总超时，通常会留下一个尴尬状态：页面已经提示失败，后台工具却还在继续，稍后又把结果写回去。更稳妥的做法是把截止时间传进工具函数，让取消信号一路可见，并把超时明确记录成一种业务状态。

先把一条 AI 工具链拆成三个时钟

在常见的工具调用流程里，模型先返回一个工具名和参数，应用校验参数后调用外部服务，再把工具结果作为下一轮输入交给模型。模型本身并不会替应用完成这个外部调用，真正持有网络连接、数据库连接和取消责任的是你的服务。

因此至少要区分三个时钟：用户请求的总截止时间、一次工具调用的截止时间，以及重试或补偿允许消耗的预算。比如总预算是 8 秒，搜索工具最多 3 秒，剩余时间还要留给结果整理；工具超时后不能再无条件重试两次，否则外层 8 秒只是一个看起来很漂亮的数字。

最小实现：让 deadline 进入工具函数

Go 的 context.Context 可以携带截止时间和取消信号。工具函数要接收这个 context，并在等待外部结果时把它交给支持 context 的客户端；如果是自己维护的循环或队列，也要主动检查 ctx.Done()。

type ToolResult struct {
    Output string
    State  string // ok, timeout, canceled, failed
}

func runTool(parent context.Context, query string) ToolResult {
    ctx, cancel := context.WithTimeout(parent, 3*time.Second)
    defer cancel()

    output, err := fetchKnowledge(ctx, query)
    if err == nil {
        return ToolResult{Output: output, State: "ok"}
    }
    if errors.Is(ctx.Err(), context.DeadlineExceeded) {
        return ToolResult{State: "timeout"}
    }
    if errors.Is(ctx.Err(), context.Canceled) {
        return ToolResult{State: "canceled"}
    }
    return ToolResult{State: "failed"}
}

这里的关键不是把错误改名，而是先看 ctx.Err() 再决定状态。外部客户端可能返回自己的网络错误；只有 context 已经结束时，才能确认这次调用确实被截止时间或上游取消打断。defer cancel() 也不能省，它能及时释放与这个派生 context 关联的资源。

总时限和工具时限怎么配

一个实用的分配方式是先固定用户总时限，再给每个工具留出上限。下面的数字只是便于验收的起点，真正数值要用线上 p95、p99 和下游 SLA 校准。

不要在工具已经超时后，根据模型的原始工具参数直接盲目重跑。查询是否幂等、写操作是否有请求标识、外部服务是否可能已经接受请求，这些判断比“再试一次”更重要。对写入类工具，最好先使用业务幂等键，再决定是否重试。

把取消来源写进可观察状态

context deadline exceeded 只能说明当前 context 到期，不能单独说明是谁设置了这个期限。服务端应在日志中同时记录 request_id、工具名、工具截止时间、剩余总预算和取消来源。这样排查时能区分“用户关闭页面”“总请求到期”和“单工具过慢”。

func stateFromContext(ctx context.Context, parent context.Context) string {
    if errors.Is(parent.Err(), context.Canceled) {
        return "user_canceled"
    }
    if errors.Is(parent.Err(), context.DeadlineExceeded) {
        return "request_timeout"
    }
    if errors.Is(ctx.Err(), context.DeadlineExceeded) {
        return "tool_timeout"
    }
    return "tool_failed"
}

实际项目里还应把外部响应状态、连接失败、参数校验失败单独记录，别把所有错误压成一个 failed。状态越粗，后面的重试策略越容易误伤写操作；状态越清楚，前端越能给出准确提示。

超时后用户应该看到什么

超时并不等于“没有答案”，更不等于“工具一定没有执行”。面向用户可以提示“查询时间较长，尚未取得结果”，并提供重新发起或稍后查看的入口；如果系统确认外部调用已经被取消，再显示“本次查询已取消”更准确。

模型的后续回答也要受到状态约束：工具状态是 tool_timeout 时，不能让模型凭空补一个工具结果。可以把已完成的上下文交给模型，让它说明哪些信息缺失；如果没有任何可靠结果，就直接返回可恢复提示，并保留内部 request_id 供追踪。

上线前用四个场景验收

1. 工具在 1 秒内返回：状态为 ok，模型能拿到工具结果。
2. 工具在 3 秒后仍未返回：连接或查询被取消，状态为 tool_timeout，不会继续写入迟到结果。
3. 用户在工具运行中断开请求：下游收到取消，状态为 user_canceled，不触发无意义重试。
4. 工具已经提交写操作后网络断开：用幂等键查询最终状态，不能仅凭客户端超时判定写入失败。

测试时不要只断开模型接口。真正容易出问题的是工具已经拿到任务、外层却先结束的窗口。日志里至少要能把一次模型响应、工具调用和最终用户状态用同一个 request_id 串起来。

常见误区与一张速查表

• 只设 HTTP 客户端超时：连接断了不代表业务 goroutine 已停止，工具函数仍要接收并检查 context。
• 所有超时都自动重试：读操作和写操作的安全边界不同，重试前先确认幂等性。
• 给用户显示“失败”：如果外部写入状态未知，应使用“处理中或待确认”，避免误导用户重复提交。
• 只记录错误字符串：同时记录 deadline 来源、工具名和 request_id，才能判断是总时限还是单工具时限。

相关问题

工具函数不支持 context 怎么办？

优先更换或封装支持 context 的客户端。若只能调用阻塞库，至少把它放在受控 worker 中，并明确知道取消只能阻止后续结果消费，未必能中断底层操作。

工具超时后能不能让模型直接回答？

可以让模型解释缺失信息和下一步，但不能把未返回的工具结果当成事实。提示中应明确工具状态和可用上下文。

用户刷新页面会不会造成重复工具调用？

有可能。对写操作使用业务幂等键，对读操作使用短期请求标识，并在服务端判断已有结果后再决定是否重新调用。

结语：让超时成为可解释的状态

AI 工具链的稳定性不在于把所有调用都拖到最长时间，而在于每一层都知道自己还能等多久、何时必须停止、停止后如何告诉下一层。把 deadline、cancel、幂等和用户状态放在同一条链路里，超时就从一条模糊报错变成了可以验收、可以恢复的工程状态。