一、适用场景
·Agent 任务需要等待用户输入或外部依赖，稍后继续执行。
·分阶段执行任务，希望在阶段之间释放运行资源并保留当前环境。
·临时中断交互式沙箱，后续继续使用同一个 InstanceId。
二、对系统影响
·暂停成功后，实例在恢复前不再提供原有访问能力。
·暂停的实例会占用暂停实例配额，单一主账号单一地域下，默认暂停实例配额为20个，可通过 提交工单 联系我们提升配额；恢复成功后自动释放对应的暂停实例配额。
三、前提条件
·已创建目标实例，并记录实例 ID。
·使用 agr CLI 时，已按 安装与配置 完成配置。
·暂停前实例状态为 RUNNING；恢复前实例状态为 PAUSED。
执行以下命令确认 CLI、凭证和实例状态：
agr version -o json –non-interactiveagr status -o json –non-interactiveagr instance get <instance-id> -o json –non-interactive
如果没有可用实例，请先参考 启动 Sandbox Instance 创建实例，并记录返回的 Data.InstanceId。
四、状态与完成判定
暂停与恢复涉及以下状态：
| 状态 | 含义 | 后续操作 |
| RUNNING | 实例正在运行 | 可以暂停或停止。 |
| PAUSING | 暂停请求已受理，平台仍在处理 | 继续查询，不能立即恢复。 |
| PAUSED | 暂停完成 | 可以恢复或停止。 |
| PAUSE_FAILED | 暂停失败 | 查询实例后重试暂停，或停止实例。 |
| RESUME_FAILED | 恢复失败 | 查询实例后重试恢复，或停止实例。 |
暂停默认会在服务端同步等待完成；大多数请求返回时实例已经进入 PAUSED。只有同步等待时间用尽、暂停仍未完成时，操作才继续在后台推进。云 API 会通过 InstanceStatus=PAUSING 明确返回这种退化情况；E2B 接口则返回冲突错误，不会把仍在进行的暂停当作成功。
恢复完成以实例回到 RUNNING 为准。
六、1. 暂停实例
INSTANCE_ID="<instance-id>"agr instance pause "$INSTANCE_ID" -o json –non-interactive
命令返回 RequestId 表示请求已受理：
{ "SchemaVersion": "agr.v1", "Command": "instance.pause", "Status": "succeeded", "Data": { "RequestId": "<request-id>" }, "Failure": null}
请避免对同一个实例并发发起多个暂停或恢复请求。
七、2. 确认暂停结果
agr instance pause 当前只展示 RequestId，因此命令返回后查询一次实例状态：
agr instance get "$INSTANCE_ID" -o json –non-interactive
·PAUSED：暂停已经完成。
·PAUSING：暂停仍在后台进行。不要重复调用暂停，可稍后再次查询。
·PAUSE_FAILED、FAILED、STOPPING 或 STOPPED：停止等待，并按对应状态处理。
CLI 适合人工确认状态。如果需要在程序中自动等待暂停完成，请使用云 API，并设置查询间隔与总等待时间。
八、3. 恢复实例
agr instance resume "$INSTANCE_ID" -o json –non-interactiveagr instance get "$INSTANCE_ID" -o json –non-interactive
恢复命令返回 RequestId 表示请求已受理。再次查询时，Data.Status 为 RUNNING 表示恢复完成。如果返回 RESUME_FAILED，请确认实例状态和配额后再重试恢复。
九、4. 清理实例
不再使用实例时，执行：
agr instance delete "$INSTANCE_ID" -o json –non-interactiveagr instance get "$INSTANCE_ID" -o json –non-interactive
实例进入 STOPPED 后不能再恢复。
十、使用 云 API
云 API 请求域名为 ags.tencentcloudapi.com，实例相关 Action 的 Version 为 2025-09-20。以下示例只展示业务参数，实际调用时还需携带标准 云 API 公共参数。
十一、1. 暂停实例
调用 PauseSandboxInstance：
{ "Action": "PauseSandboxInstance", "InstanceId": "<instance-id>"}
服务端会先同步等待暂停完成。成功响应包含请求 ID 和返回时刻的实例状态：
{ "Response": { "RequestId": "<request-id>", "InstanceStatus": "PAUSED" }}
InstanceStatus 的处理方式：
·PAUSED：暂停已经完成，可以恢复。
·PAUSING：暂停仍在后台进行，请调用 DescribeSandboxInstanceList 查询状态。
·请求返回错误：结合错误码和实例查询结果判断是否进入 PAUSE_FAILED，或是否仍为 RUNNING。
十二、2. 在 PAUSING 时查询状态
仅当 PauseSandboxInstance 返回 InstanceStatus=PAUSING 时，才需要调用：
{ "Action": "DescribeSandboxInstanceList", "InstanceIds": ["<instance-id>"]}
建议每 2～5 秒查询一次，并设置总等待时间。状态变为 PAUSED 后可以恢复；状态变为 PAUSE_FAILED、STOPPING 或 STOPPED 时停止查询并按对应状态处理；超过总等待时间后返回超时，不要继续无限轮询。
十三、3. 恢复实例
调用 ResumeSandboxInstance：
{ "Action": "ResumeSandboxInstance", "InstanceId": "<instance-id>"}
如需设置恢复后的运行时长，可传入 duration 格式的 Timeout：
{ "Action": "ResumeSandboxInstance", "InstanceId": "<instance-id>", "Timeout": "30m"}
成功响应包含 RequestId。随后调用 DescribeSandboxInstanceList；状态为 RUNNING 表示恢复完成，状态为 RESUME_FAILED 表示恢复失败。
十四、使用 E2B Python SDK
E2B Python SDK 通过 pause() 暂停，通过 Sandbox.connect() 连接并恢复已暂停实例。
from e2b import Sandboxsandbox = Sandbox.create(template="<tool-id>", timeout=300)sandbox_id = sandbox.sandbox_idtry: sandbox.pause() # pause() 正常返回表示暂停已经完成，不需要再轮询状态。 sandbox = Sandbox.connect(sandbox_id)finally: sandbox.kill()
E2B 接口与 云 API 的返回语义不同：
·pause() 正常返回时，服务端已经确认实例进入 PAUSED，可以直接调用 Sandbox.connect()。
·如果同步等待时间用尽、实例仍在暂停，E2B 接口会返回冲突错误，提示暂停仍在进行；它不会像 云 API 一样成功返回 InstanceStatus=PAUSING。
·遇到“暂停仍在进行”的冲突错误时，不要立即重复调用 pause()，也不要用 get_info() 无限轮询。确实需要随后恢复时，可以为 Sandbox.connect() 设置总超时，并使用有上限的指数退避重试。
·E2B 标准 state 字段不能精确表达 PAUSING 和 PAUSE_FAILED。AGS 会在返回对象的 metadata["x-ags-sandbox-state"] 中提供真实生命周期状态，例如 running、paused、pausing、pause_failed 和 resume_failed。
·读取 E2B 返回对象时，如需区分细粒度生命周期状态，请使用 metadata["x-ags-sandbox-state"]；标准 state 字段仅用于保持 E2B SDK 兼容。
十六、为什么暂停后仍可能看到 PAUSING？
暂停默认会同步等待完成。只有服务端等待时间用尽、暂停仍未完成时，操作才在后台继续。云 API 会返回 InstanceStatus=PAUSING；agr 未展示该字段时可以查询一次实例状态。此时请执行有上限的状态查询，进入 PAUSED 后再恢复。E2B 则会返回冲突错误，不会把 PAUSING 当作暂停成功。
十七、暂停失败后怎么办？
先查询实例状态。如果状态为 PAUSE_FAILED，可以重试暂停；如果实例仍为 RUNNING，确认业务仍可访问后再决定是否重新暂停；不再需要时直接停止实例。
十八、恢复失败后怎么办？
先查询实例状态和健康状态，并检查应用日志与探针结果。如果状态为 RESUME_FAILED，或恢复后健康状态持续为 unhealthy，请勿无限重试恢复，也不要停止实例或重新创建，以免丢失故障现场。请保留当前实例，记录 InstanceId、RequestId、应用日志和探针结果，并联系 AGS 团队排查。
十九、暂停后还能直接停止吗？
可以。实例不再需要时可以直接停止，无需先恢复。
20、最佳实践
·使用 云 API 时先检查 PauseSandboxInstance 返回的 InstanceStatus：PAUSED 无需轮询，只有 PAUSING 才执行有上限的状态查询。
·使用 E2B 时，pause() 正常返回后可以直接连接恢复；只有收到“暂停仍在进行”的冲突错误时，才执行有上限的连接重试。
·只对确认已暂停的实例发起恢复，并为状态查询和重试设置总超时。
·避免对同一实例并发暂停、恢复或停止。
·不再使用实例时及时停止，避免长期占用暂停实例配额。
21、相关文档
·启动 Sandbox Instance
·查询 Sandbox Instance
·实例生命周期
·停止与超时