给 Agent 配一个 timeout：30_000 并不代表它真的会在 **30 秒** 内结束。其实，Agent 的外层、模型请求、工具调用、重试退避还有持久化。只要有一层重新计时使用者看到的时间就可能被拉长到 **40+ 秒** 或更久；按理说，更危险的是前端已经显示“已超时”，后台工具却仍在继续写数据。导致 Token 被无谓消耗并产生副作用。

官方版本核验给出了三个值得组合的信号：

• Vercel AI SDK 修复了 ToolLoopAgent 没有遵守 Agent 超时设置。
• Pydantic AI 把取消提高为一级 Runtime 事件。
• Google GenAI Python 增加了终态 TOO_MANY_TOOL_CALLS。

这篇文章不比较框架 API，而是用一个的 TypeScript 最小实验拆开一条通用超时契约。

一、最常见的错误：每一层都从头计时

下面的代码看起来给模型和工具都加了 **10 秒** 超时但允许整轮至少跑 **20+ 秒**；再加两次重试，时间会继续膨胀。

await withTimeout => callModel,10_000);await withTimeout => callTool,10_000);await retry => callModel。{
attempts : 3,timeoutMs : 10_000,});

失效方式	表面配置	实际风险
每层重新计时		总运行时间至少为多倍单步超时时间；前端已报“超时”，后台仍继续执行。
预算在每次尝试后重置		相同的预算被多次消费；出现 Token 损失与重复副作用。
错误返回仅为 “error” 状态		无法判断是否可重试或是否已产生副作用。
前端取消不下传 UI 显示 “已停止”		后台仍花费 Token 或执行工具，造成资源浪费与业务异常。

真正入口应采用绝对截止时间（deadlineAt} ;其实，后续每一层只能消费剩余预算，而不能创建新的完整预算。说起来，

二、把相对 timeout 转成绝对 deadline

入口接到使用者请求时只计算一次截止时间。同时保留父级取消信号，模型、工具和退避拿到的是同一个上下文。

type RunBudget = {
deadlineAt : number;parentSignal : AbortSignal;perStepCapMs : number;reserveMs : number;}，const budget : RunBudget = {
deadlineAt : Date.now + 30_000。parentSignal : request.signal,perStepCapMs : 8_000,reserveMs : 1_000,};

reserveMs 并非给业务继续运行，而是留给终态持久化、Trace 收尾和使用者响应留空间。没有这段余量，程序可能在最终一毫秒完成工具。却来不及写入“工具是否执行成功”。分布式程序还需处理跨机器时钟；这篇文章实验只在单进程使用 Date.now.

三、每一步只能拿到剩余预算与单步上限的较小值

实验在启动步骤前计算：<=0 时该步骤根本不应启动：

const allocatedMs = Math.min(
perStepCapMs。Math.max - reserveMs),);if {
return { terminal:"deadline-exceeded" };}

单步上限用于防止一个挂起工具吃完全部时间；总截止时间负责限制整个 run。生产实现还需把信号真正接到 Provider SDK、,数据库驱动、子进程和队列使用者。按理说，只在外层使用一次 Promise.race 一个计时器通常不会停止底层工作。

四、使用者取消和预算耗尽必须是两种终态

"使用者点击停止" 表达主动意图；"deadline exceeded" 表达程序没在承诺时间内完成。二者都要向下传播，但重试、提示与指标不同。

const controller = new AbortController;const cancel = => controller.abort);parentSignal.addEventListener;const timer = setTimeout(
=> controller.abort),allocatedMs
);controller.signal.addEventListener;
function handleAbort{
// propagate cancellation downstream
}

Pydantic AI 的一级取消事件说明这不是 UI 层细节，而是 Runtime 契约。这篇文章未安装该框架，只吸收这一通用判断。

五、重试花的是同一笔钱。不能刷新预算

重试前至少检查：错误是否允许重试、是否还有 attempt，还有剩余预算是否覆盖退避。如果连退避都放不下应立即结束.

const remaining = deadlineAt - Date.now - reserveMs;其实，if {
return fail;}
if {
return { terminal:"deadline-exceeded" };话说回来，}
await waitFor;// 下一次仍使用原来的 deadlineAt

对写操作还要增加幂等键与结果回查。连接在提交后断开时“超时”不等于“没有执行”；若不先查询真实结果就重试发布/支付/写库，可能制造重复副作用.

六、把失败终态建模清楚。恢复逻辑才有依据

< td>provider‑rejected < td>tool‑failed

终态	是否可直接重试	必须记录
completed	否	结果 、耗时 、用量
cancelled	通常否
deadline‑exceeded	视幂等性决定
too‑many‑steps	否

type StepRecord = { name : string;kind : "model" | "tool";attempt : number;allocatedMs : number;按理说，outcome : | "completed" | "retrying" | "failed" | "timed-out";sideEffectStarted:boolean;}，

Google GenAI Python 把“工具调用次数耗尽”暴露为 tooMANYTOOL_CALLS< /kbd>,说明步骤上限不是普通完成。Adapter 应保留 Provider 原始 finish reason，再映射到业务终态。

            

• 用本地计时器 + 模拟步骤验证总预算传播
• 不调用真实模型或外部工具
• 在 Bun + TypeScript + Biome 环境下编译通过

ts Biome这方面。Checked files. No fixes applied. TypeScript --noEmit: passed fail expect calls

{"operations": /.../,"retries": /.../,"terminal":"completed"}

测试覆盖共享 deadline挂起工具超时、 使用者取消、 瞬时错误重试、 预算不足拒绝退避、 Step 上限还有 工具失败后的副作用标记。它并未证明任何 SDK 当前版本已经正确实现。

用慢模型 / 永不返回的工具 / 数据库提交后断线做故障注入；怎么说呢，再覆盖取消与完成同时发生、 超时与工具回调同时发生、 一个并行分支失败而同级分支是否停止。恢复 Worker 后还要检查旧 deadline attempt 审批和副作用状态是否仍有效。

ts expect.toBe;expect.toBe，expect.toBe;expect.toBe，不过，

从观测至少记录来看。

• remaining_ms_before_step 与 allocated_step_ms——确保剩余时间被正确扣除。
• cancelSource——谁触发了取消。
• attempt 与 stepCount——追踪各级别尝试次数。
• originalFinishReason——Provider 返回的原始 finish reason，用于映射业务终态。老实说，
• isBillingEnabled 与 sideEffectState——避免记录凭据或完整敏感正文。同时评估成本与风险，

入口只生成一次绝对 deadline，后续层不重置；
每步预算取剩余时间与单步上限的较小值；
为持久化 / Trace / 响应保留收尾时间；
父级取消传播到模型 / 工具 / 并行任务 / 折返退避；
取消 / 超时 / Step 耗尽 / 工具失败是不同终态；
重试不刷新 deadline，预算不足则中止退避；
• 写工具有幂等键／结果回查／副作用审计；
• 用挂起／慢响应／取消竞态／提交后断线做故障注入。话说回来，

Vercel AI SDK ai@…| Pydantic AI v2 | Google GenAI Python v2 |             | 官方来源： Vercel AI SDK a@…<\/kbd>,Pydantic AI b…<\/kbd>,Google GenAI Python b…<\/kbd>. 📖📦📺✔🔗🗃<\/span>

说到验证边界，这篇文章；未安装上述 SDK，也未调用真实模型/数据库/队列或发布工具。也未验证分布式钟点差异或 Provider 实际延迟调整。

---