Agent Runtime 实例状态查询

一、查询入口

建议先检查本地 CLI 配置和云端连通性，再执行实例状态查询。

agr status -o jsonagr 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 jsonagr 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、最近一次操作结果和实例更新时间一起判断。

九、查询单个实例

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 jsonagr instance get <instance-id> -o json

更新命令仅适用于 RUNNING 状态的实例。执行后请再次查询，确认 TimeoutSeconds 和 ExpiresAt 已同步变化。

十三、暂停实例

agr instance pause <instance-id> -o jsonagr instance get <instance-id> -o json

暂停命令适用于 RUNNING 或 PAUSE_FAILED 状态的实例。建议以二次查询结果作为验证信号，确认状态已转为 PAUSED。

十四、恢复实例

agr instance resume <instance-id> -o jsonagr instance get <instance-id> -o json

恢复命令适用于 PAUSED 或 RESUME_FAILED 状态的实例。恢复成功后，请再次查询实例状态，确认实例已回到 RUNNING。

十五、停止实例

agr instance delete <instance-id> -o jsonagr 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。