手动停止 Sandbox Instance、在创建时设置运行时长，以及在实例运行期间调整超时配置。
适用场景
主动停止不再使用的实例，释放运行配额。
在创建实例时显式限制可运行时长，避免任务结束后长时间占用资源。
在实例仍处于运行中时延长或缩短超时窗口。
通过实例详情区分手动停止与超时回收。
开始前准备
已安装
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
重点字段如下：
字段 | 含义 |
Data.Status | 当前实例状态，例如 RUNNING、STOPPING、STOPPED |
Data.TimeoutSeconds | 当前生效的超时值，单位为秒 |
Data.ExpiresAt | 当前超时窗口对应的预计结束时间 |
Data.StopReason | 停止原因；常见值包括 manual、timeout、error、system |
Data.Persistent | 是否为常驻实例；为 true 时不参与 timeout 自动回收 |
通过兼容 E2B 的 HTTP 接口查询实例详情时，对应可观察字段为
state 和 endAt。常见错误
场景 | 表现 | 处理建议 |
删除不存在的实例 | agr instance delete 返回 INSTANCE_NOT_FOUND | 确认 InstanceId 是否正确；如果目标可能已经不存在，可追加 --ignore-not-found。 |
更新非 RUNNING 实例的超时 | 更新请求失败 | 先执行 agr instance get 确认实例状态；已停止实例需要重新创建。 |
更新超时为 0、负数或非法格式 | 更新请求失败 | 对 agr instance update 使用 10m、300s 等合法 duration；对 E2B 兼容控制面请求使用大于 0 的秒级整数。 |
更新 Persistent=true 的实例超时 | 更新请求失败 | 常驻实例不依赖 timeout 回收；如需结束实例，请直接停止。 |
