Agent Runtime 停止与超时

一、适用场景

·主动停止不再使用的实例，释放运行配额。

·在创建实例时显式限制可运行时长，避免任务结束后长时间占用资源。

·在实例仍处于运行中时延长或缩短超时窗口。

·通过实例详情区分手动停止与超时回收。

二、开始前准备

·已安装 agr CLI。

·已通过环境变量或 CLI 配置文件提供可用凭证。

·已获取目标实例的 InstanceId；如果要创建新实例，还需要准备可用的 ToolId 或 ToolName。

执行以下命令确认 CLI 和凭证就绪：

agr version -o json –non-interactiveagr status -o json –non-interactiveagr doctor -o json –non-interactive

预期结果：

·agr version 返回 CLI 版本和 commit 信息。

·agr status 用于查看 CLI 当前读取到的配置与凭证来源；重点检查 Data.Auth.SecretId.Present 和 Data.Auth.SecretKey.Present 是否都为 true。

·agr doctor 用于做凭证与连通性自检；当 SecretId、SecretKey、Connectivity 等检查项都为 ok 时，可继续执行后续实例操作。

三、使用 agr CLI 停止

执行以下命令停止一个或多个实例：

agr instance delete <instance-id> [instance-id…] -o json

如果实例可能已被清理，可追加 –ignore-not-found，将“实例不存在”视为成功。

预期结果：

·命令返回结构化 JSON 结果。

·删除请求提交后，实例先进入 STOPPING，完成后进入 STOPPED。

验证方式：

agr instance get <instance-id> -o json –non-interactive

重点检查以下字段：

·Data.Status：预期从 RUNNING 变为 STOPPING 或 STOPPED。

·Data.StopReason：手动停止时为 manual。

·Data.ExpiresAt：停止完成后不再继续延长。

兼容 E2B 的 HTTP 接口也可用于停止实例：

DELETE /sandboxes/{sandboxID}

该接口成功时返回 204 No Content。如需确认实例已结束，请继续调用实例详情接口检查 state。

清理说明：

·停止操作不可回滚。误停后需要重新创建实例。

·如果只是临时释放资源并计划稍后恢复，请优先评估暂停/恢复能力。

四、使用 agr CLI 创建限时实例

执行以下命令，在创建时直接设置实例超时：

agr instance create –tool-id <tool-id> –timeout 30m -o json

–timeout 支持 duration 字符串，例如 5m、30m、300s；纯数字按秒处理。默认值为 5m。

验证方式：

agr instance get <instance-id> -o json –non-interactive

重点检查以下字段：

·Data.Status：实例启动完成后应为 RUNNING。

·Data.TimeoutSeconds：返回秒级超时值。

·Data.ExpiresAt：返回实例预计结束时间。

创建实例时，也可通过兼容 E2B 的 HTTP 接口在请求体中传入秒级 timeout 字段；创建完成后建议通过实例详情接口复核实际生效值。

五、使用 agr CLI 更新超时

当实例仍处于运行中时，执行以下命令调整超时：

agr instance update <instance-id> –timeout 45m -o json

–timeout 支持 duration 字符串，例如 10m、45m、300s。

限制说明：

·只有 RUNNING 状态的实例支持原地更新超时。

·Persistent=true 的实例不受 timeout 回收限制，不能通过该命令修改超时。

·取值必须大于 0。

验证方式：

agr instance get <instance-id> -o json –non-interactive

重点检查以下字段：

·Data.Status：更新后应保持为 RUNNING。

·Data.TimeoutSeconds：更新为新的秒数。

·Data.ExpiresAt：随新的超时窗口刷新。

六、查看超时与停止原因

执行以下命令查看当前实例状态：

agr instance get <instance-id> -o json –non-interactive

重点字段如下：

通过兼容 E2B 的 HTTP 接口查询实例详情时，对应可观察字段为 state 和 endAt。

七、常见错误