文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>Agent Runtime>操作指南>可观测性>实例状态查询

实例状态查询

最近更新时间：2026-06-03 09:09:01

我的收藏

本页目录：

Agent Sandbox 实例通过 Status 表示生命周期阶段，通过 StopReason 表示停止原因。本文说明实例状态的含义、各状态下可执行的操作，以及使用 agr CLI 查询状态的方式。
本文中的查询命令均为只读操作，不会修改实例状态、超时时间或运行配置。
说明：
查询单个实例时，优先使用 agr instance get <instance-id> -o json。
批量查询实例时，使用 agr instance list -o json；按状态筛选时，通过 --filters 传入 JSON 条件。

查询入口

建议先检查本地 CLI 配置和云端连通性，再执行实例状态查询。
agr status -o json
agr doctor -o json
agr status -o json 返回示例：
{
  "SchemaVersion": "agr.v1",
  "Command": "status",
  "Status": "succeeded",
  "Data": {
    "Auth": {
      "SecretId": { "Present": true, "Source": "TENCENTCLOUD_SECRET_ID" },
      "SecretKey": { "Present": true, "Source": "TENCENTCLOUD_SECRET_KEY" }
    },
    "ConfigFound": false,
    "ConfigLoaded": false,
    "EffectiveOutput": "json",
    "Domain": "tencentags.com",
    "Region": "ap-guangzhou"
  },
  "Failure": null,
  "Warnings": []
}
Status 为 succeeded 表示 CLI 本地配置读取成功。
Data.Auth.SecretId.Present 和 Data.Auth.SecretKey.Present 同时为 true 时，表示当前 shell 已注入可用的云 API 凭证。
Data.Domain 和 Data.Region 可用于确认当前访问域名和地域。
agr doctor -o json 返回示例：
{
  "SchemaVersion": "agr.v1",
  "Command": "doctor",
  "Status": "succeeded",
  "Data": {
    "Checks": [
      { "Name": "Output", "Status": "ok", "Message": "output format is json" },
      { "Name": "SecretId", "Status": "ok", "Message": "SecretId is configured" },
      { "Name": "SecretKey", "Status": "ok", "Message": "SecretKey is configured" },
      { "Name": "Connectivity", "Status": "ok", "Message": "API reachable, credentials valid" }
    ]
  },
  "Failure": null,
  "Warnings": []
}
Checks 中的 Connectivity 为 ok，且消息为 API reachable, credentials valid 时，表示当前环境已具备查询实例状态所需的连通性和凭证。
如果 Connectivity 显示凭证缺失或网络错误，请先修复 CLI 鉴权或网络访问，再执行实例查询。
实例状态通过以下命令获取：
agr instance get <instance-id> -o json
agr instance list -o json
建议重点查看返回结果中的 Status、StopReason、TimeoutSeconds 和 ExpiresAt 字段。

状态总览

状态
含义
典型进入条件
支持的操作
是否终态
STARTING
实例已受理创建请求，仍在启动
创建实例后，平台尚未完成启动
查询
否
RUNNING
实例已运行，可访问
创建成功；或从暂停态恢复成功
查询、更新、暂停、停止
否
FAILED
实例运行期间进入异常状态
运行中实例出现异常
查询、停止
否
PAUSING
已开始暂停，状态尚未落稳
对实例发起暂停后，平台仍在处理
查询、停止
否
PAUSED
实例已暂停，运行状态被保留
暂停成功
查询、恢复、停止
否
PAUSE_FAILED
暂停失败
暂停流程执行失败
查询、重试暂停、停止
否
RESUME_FAILED
恢复失败
恢复流程执行失败
查询、重试恢复、停止
否
STOPPING
已开始停止，尚未完成
对实例发起停止后，平台仍在处理
查询
否
STOPPING_FAILED
停止失败
停止流程执行失败
查询、重试停止
否
STOPPED
实例已停止完成
手动停止成功；超时回收成功；生命周期到期回收成功
查询
是
STARTING_FAILED
启动失败，未进入运行态
创建流程失败
查询
是

状态说明

STARTING 与 STARTING_FAILED

STARTING 表示实例正在创建，通常只需要继续查询，直到状态转为 RUNNING 或 STARTING_FAILED。STARTING_FAILED 表示实例未成功进入可用态，建议检查 Tool 配置、镜像、网络和启动参数后重新创建实例。

RUNNING

RUNNING 表示实例已经可访问。该状态下支持以下管理操作：
更新：agr instance update <instance-id> --timeout 30m -o json
暂停：agr instance pause <instance-id> -o json
停止：agr instance delete <instance-id> -o json
执行变更后，建议再次运行 agr instance get <instance-id> -o json，确认状态和关键字段已经更新。

FAILED

FAILED 表示实例在运行过程中进入异常状态。此时可以继续查询实例详情，并通过停止操作回收异常实例。

PAUSING、PAUSED、PAUSE_FAILED、RESUME_FAILED

PAUSING 表示暂停请求已受理，平台仍在处理暂停流程。该状态下可以继续查询，也可以直接发起停止。
PAUSED 表示实例已经暂停，运行状态被保留。后续可执行恢复或停止。
PAUSE_FAILED 表示暂停流程失败。可以重试暂停，也可以直接停止实例。
RESUME_FAILED 表示恢复流程失败。可以重试恢复，也可以直接停止实例。

STOPPING、STOPPING_FAILED、STOPPED

STOPPING 表示停止请求已下发，停止尚未完成。建议继续查询，等待状态转为 STOPPED 或 STOPPING_FAILED。
STOPPING_FAILED 表示停止流程失败，可以再次执行停止命令重试。
STOPPED 表示实例已停止完成。若需继续使用该工作负载，请重新创建实例。

StopReason

实例进入停止态后，可通过 StopReason 判断停止来源。
枚举值
含义
典型场景
manual
手动停止
用户主动执行停止操作
timeout
超时停止
实例达到设置的超时时间后被回收
lifetime_expired
生命周期到期停止
实例达到生命周期上限后被回收
error
异常停止
系统在异常停止场景写入该值
system
系统停止
系统回收或维护类场景写入该值
当前实例响应未单独返回暂停原因字段。排查暂停或恢复问题时，建议结合 Status、最近一次操作结果和实例更新时间一起判断。

CLI 主路径

查询单个实例

agr instance get <instance-id> -o json
执行该命令后，建议重点关注以下返回字段：
字段
作用
Data.Status
实例当前生命周期状态，例如 RUNNING、PAUSED、STOPPED
Data.StopReason
实例停止来源，例如手动停止、超时回收或系统回收
Data.TimeoutSeconds
实例当前超时配置，便于核对剩余运行窗口
Data.ExpiresAt
实例预计过期时间，适合与停止策略一起判断
当实例处于停止或异常状态时，可结合 StopReason 判断后续处理方式。

查询某个 Tool 下的实例

agr instance list --tool-id <tool-id> -o json
--tool-id 用于查询某个 Tool 下的所有实例。请求支持以下筛选和分页参数：
--tool-id：指定 Tool ID。
--filters：传入 JSON 格式的筛选条件。
--offset / --limit：分页控制。
--instance-ids：按实例 ID 精确查询。
返回结果中可重点查看 Data.InstanceSet[].InstanceId、Data.InstanceSet[].Status 和 Data.TotalCount。
同一个 Tool 下有多个实例时，可以先按 Tool 聚合，再观察是否存在同类状态集中出现的情况。

按状态筛选实例

agr instance list --filters '[{"Name":"Status","Values":["RUNNING"]}]' -o json
--filters 接受 JSON 数组格式的筛选条件，通过 Name 和 Values 指定筛选字段和目标值。返回结果中建议关注：
Data.InstanceSet[].InstanceId：命中的实例 ID。
Data.InstanceSet[].Status：命中的生命周期状态。
Data.TotalCount：当前筛选条件下的实例总数。
如需查看暂停、恢复失败或停止失败实例，也可以把 Values 替换为对应状态值，例如 PAUSED、RESUME_FAILED 或 STOPPING_FAILED。

更新运行中的实例

agr instance update <instance-id> --timeout 30m -o json
agr instance get <instance-id> -o json
更新命令仅适用于 RUNNING 状态的实例。执行后请再次查询，确认 TimeoutSeconds 和 ExpiresAt 已同步变化。

暂停实例

agr instance pause <instance-id> -o json
agr instance get <instance-id> -o json
暂停命令适用于 RUNNING 或 PAUSE_FAILED 状态的实例。建议以二次查询结果作为验证信号，确认状态已转为 PAUSED。

恢复实例

agr instance resume <instance-id> -o json
agr instance get <instance-id> -o json
恢复命令适用于 PAUSED 或 RESUME_FAILED 状态的实例。恢复成功后，请再次查询实例状态，确认实例已回到 RUNNING。

停止实例

agr instance delete <instance-id> -o json
agr instance get <instance-id> -o json
停止命令适用于 RUNNING、PAUSING、PAUSED、PAUSE_FAILED、RESUME_FAILED、STOPPING_FAILED 和 FAILED 状态的实例。执行后请再次查询，确认状态已变为 STOPPED；如果结果为 STOPPING_FAILED，可以重试停止。

已知限制

agr instance pause 当前未暴露暂停模式参数。CLI 会按照服务端默认行为或工具配置执行暂停。
agr instance resume 当前未暴露恢复时超时参数。如需调整恢复后的超时时间，请在恢复成功后使用 agr instance update <instance-id> --timeout <duration> -o json。

中国站