超时与过期

概述

Agent 任务可能等待模型、Java 工具、外部工具、人工审批或用户输入。为这些操作设置时间限制，可以避免单次调用长时间占用资源，也可以防止暂停任务无限期保留。

超时配置分为两类：

类型	作用
调用超时	限制一次模型或本地工具调用可以执行多久
等待过期	限制外部工具、审批或用户输入可以等待多久

任务的总时长由 AgentBudget.maxDurationMillis(...) 控制，详见运行限制与预算。本页介绍的是单次调用和暂停等待的时间限制。

基本配置

java

AgentExecutionPolicy policy = AgentExecutionPolicy.builder()
    .modelCallTimeoutMillis(30_000)
    .toolExecutionTimeoutMillis(20_000)
    .externalToolTimeoutMillis(5 * 60_000)
    .approvalTimeoutMillis(24 * 60 * 60_000)
    .userInputTimeoutMillis(30 * 60_000)
    .suspensionExpirationStrategy(
        AgentSuspensionExpirationStrategy.FAIL_TURN)
    .build();

所有时间单位都是毫秒，值为 0 表示不设置该项限制。

调用超时

配置	限制对象	超时后的行为
`modelCallTimeoutMillis(...)`	单次同步或流式模型调用	进入统一的失败或重试流程
`toolExecutionTimeoutMillis(...)`	单次本地 Java 工具调用	请求停止工具，并进入失败或重试流程

超时不一定能立即终止底层操作。例如，HTTP 客户端可能仍在等待网络响应，Java 工具也可能忽略线程的停止信号。因此，模型客户端、数据库和第三方 HTTP 客户端仍应配置各自的连接与读取超时。

退款、扣款等工具还必须做好防重复执行。超时发生时，外部系统中的操作可能已经成功，只是 Runner 尚未收到结果。

等待过期

配置	限制对象
`externalToolTimeoutMillis(...)`	等待浏览器或其他外部执行器返回工具结果
`approvalTimeoutMillis(...)`	等待人工审批
`userInputTimeoutMillis(...)`	等待用户提交表单或补充信息

Runner 在任务暂停时记录过期时间。等待期间不会占用执行线程，任务进度可以保存到 Store，并在其他请求或进程中恢复。

等待期限到达后，任务不会主动消失。Runner 在收到迟到的恢复请求时，根据过期策略决定下一步。如果业务需要到期后自动关闭任务，应由自己的定时任务触发相应处理。

过期处理策略

suspensionExpirationStrategy(...) 支持以下选择：

策略	行为
`REJECT_RESUME`	拒绝迟到的恢复请求，任务保持等待状态；这是默认值
`FAIL_TURN`	拒绝恢复，并把任务标记为失败
`CANCEL_TURN`	拒绝恢复，并把任务标记为取消

如果业务需要允许用户重新提交，应由业务系统明确创建新的审批、表单或任务流程，不要直接忽略过期检查。

与总时长预算的区别

假设一个任务配置如下：

总时长上限为 10 分钟；
单次模型调用上限为 30 秒；
人工审批等待上限为 24 小时。

由于总时长从 AgentTurn 创建时开始计算，任务等待审批 10 分钟后会先达到总时长预算，而不会等到审批期限。因此，包含长时间人工等待的任务需要合理设置总时长，或者不使用过短的总时长预算。

配置建议

模型调用、Java 工具和底层网络客户端都应设置超时。
审批和用户输入的等待时间应符合实际业务流程。
对迟到结果给出明确提示，不要静默丢弃用户提交。
超时后可能重复执行的工具必须使用幂等键。
监控调用超时、等待过期以及最终失败或取消的数量。

超时与过期 ​

概述 ​

基本配置 ​

调用超时 ​

等待过期 ​

过期处理策略 ​

与总时长预算的区别 ​

配置建议 ​

相关文档 ​