Sandbox Instance 需要临时中断、稍后继续使用时，可以将实例从
RUNNING 暂停到 PAUSED，再恢复到 RUNNING。适用场景
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
状态与完成判定
暂停与恢复涉及以下状态：
状态 | 含义 | 后续操作 |
RUNNING | 实例正在运行 | 可以暂停或停止。 |
PAUSING | 暂停请求已受理，平台仍在处理 | 继续查询，不能立即恢复。 |
PAUSED | 暂停完成 | 可以恢复或停止。 |
PAUSE_FAILED | 暂停失败 | 查询实例后重试暂停，或停止实例。 |
RESUME_FAILED | 恢复失败 | 查询实例后重试恢复，或停止实例。 |
暂停默认会在服务端同步等待完成；大多数请求返回时实例已经进入
PAUSED。只有同步等待时间用尽、暂停仍未完成时，操作才继续在后台推进。云 API 会通过 InstanceStatus=PAUSING 明确返回这种退化情况；E2B 接口则返回冲突错误，不会把仍在进行的暂停当作成功。恢复完成以实例回到
RUNNING 为准。使用 agr CLI
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 团队排查。暂停后还能直接停止吗？
可以。实例不再需要时可以直接停止，无需先恢复。
最佳实践
使用 云 API 时先检查
PauseSandboxInstance 返回的 InstanceStatus：PAUSED 无需轮询，只有 PAUSING 才执行有上限的状态查询。使用 E2B 时，
pause() 正常返回后可以直接连接恢复；只有收到“暂停仍在进行”的冲突错误时，才执行有上限的连接重试。只对确认已暂停的实例发起恢复，并为状态查询和重试设置总超时。
避免对同一实例并发暂停、恢复或停止。
不再使用实例时及时停止，避免长期占用暂停实例配额。
相关文档
实例生命周期
停止与超时
