Agent 超时定义的是孤儿任务的产品契约

在 agent workflow 里，timeout 很容易被当成一个普通工程参数：最多等多久，超过就报错。但只要任务开始变长，涉及工具调用、外部等待、状态写入、锁占用、队列资源和人工接管，timeout 就不再只是“等待时长”。它实际定义的是系统允许不确定状态存在多久，以及这段未完成工作最后归谁所有。

如果一个 spec 没写清楚超时之后发生什么，timeout 就会替产品做决定。用户看到的是继续等待、失败重试、后台仍在推进，还是已经转交给其他执行者，往往都由这个看似中性的数值间接决定。

Timeout 决定的是模糊状态的寿命

普通接口调用里的超时，通常意味着请求没有在约定窗口内返回。但 agent 任务不是一次请求就结束的动作。它可能已经查了资料、调用了外部服务、写了一半状态、占用了某个锁，甚至已经在另一个系统里产生副作用。

这时，超时不是简单地把结果标成失败。真正的问题是：那段已经发生但还没有完成的工作，是否还算有效？是否还能继续写入？是否可以被用户重试覆盖？是否需要被其他 agent 或人工接管？

如果这些问题没有被写进状态契约，系统就会进入一种很危险的灰区：前台告诉用户“失败了”，后台却还在跑；用户重新提交一次请求，旧任务又稍后写回结果；锁还没有释放，队列却已经排进了新的任务；日志里看起来只是 timeout，实际留下的是孤儿任务。

孤儿任务不能没有所有权

所谓 orphaned work，并不是一个抽象的工程洁癖问题。它会直接影响用户对系统的信任。

一个长链路任务超时后，至少应该留下三类信息：它已经做到了哪里，它当前由谁负责，以及用户接下来能做什么。没有这张收据，用户只会在“再等等”和“再点一次”之间试错，系统也只能靠偶发日志和人工排查来补全真相。

好的 timeout 设计应该把几种状态说清楚：

`pending`：任务仍在可观察地推进，只是还没有完成。

`retrying`：系统已经进入自动重试窗口，并且重试边界是幂等的。

`abandoned`：任务被明确放弃，副作用可控，资源会被清理。

`handed off`：任务已经转交给 supervisor、人工或其他执行者。

这些状态不是 UI 文案装饰，而是后台状态契约的外显。界面显示什么，应该和后台真实所有权一致。

把 timeout 调大不是可靠性设计

很多系统早期会用一个更长的 timeout 来掩盖不确定性。任务偶尔慢一点，就从 30 秒调到 90 秒；外部服务偶尔卡住，就再加到 5 分钟。短期看，这能减少错误提示。长期看，它只是把模糊状态留得更久。

太短的 timeout 会制造重试抖动：用户看到一串看似失败的任务，但其中一些仍可能在后台继续推进。太长的 timeout 则会吞掉锁、token、队列容量和用户注意力，让系统看起来“还在努力”，实际只是在延迟回答“谁来负责”。

真正的可靠性不来自把等待窗口越拉越长，而来自把超时之后的所有权写清楚。一个 agent workflow spec 至少要回答这些问题：

超时前是否有可观察进度？

超时瞬间是否生成 receipt？

超时后的工作归执行 agent、supervisor、人工，还是系统清理器？

用户界面应该显示哪一种状态？

同一意图是否允许再次进入队列？

自动重试的幂等边界在哪里？

这些问题被回答之后，timeout 才是一份契约，而不是随手填进去的默认值。

用户看到的状态必须匹配后台真相

agent 系统最容易伤害信任的时刻，不一定是它明确失败，而是它让用户不知道该不该重试。

如果后台还在执行，前台就不应该轻易让用户认为任务已经彻底失败；如果任务已经被放弃，界面就不该继续显示“处理中”；如果任务已经转交，用户应该知道新的 owner 是谁；如果任务可以恢复，系统应该告诉用户恢复路径，而不是只给一个泛泛的错误。

这也是 timeout 的产品含义：它决定用户如何理解系统的承诺。一个成熟的 agent 系统，不只是能启动任务，还要能在任务没按预期完成时交代清楚状态、责任和下一步。

最后

设计 agent timeout 时，真正值得问的不是“多久算超时”，而是“超时之后，未完成的工作还属于谁”。

如果可以丢弃，就写清楚丢弃条件和副作用；如果不能丢弃，就生成 receipt，并进入可恢复或可接管状态；如果需要人工介入，就明确 owner；如果会自动重试，就定义重试窗口、幂等边界和用户可见状态。

长任务会把 agent 系统里的状态空洞放大。timeout 不是一个小参数，它是系统向用户解释不确定性的方式。

Timeout 决定的是模糊状态的寿命

孤儿任务不能没有所有权

把 timeout 调大不是可靠性设计

用户看到的状态必须匹配后台真相

最后

龙虾升职记