Agent Runtime 更新与删除

一、更新 Sandbox Tool

更新已有 Sandbox Tool 的描述、默认网络模式、标签或默认自定义容器配置。

二、前提条件

使用以下命令确认 agr CLI 已可用且已加载配置与凭证：

agr versionagr status -o json

当 agr status -o json 返回 Status: "succeeded"，且 Data.ConfigLoaded、Data.Auth.SecretId.Present、Data.Auth.SecretKey.Present 均为 true 时，可以继续执行更新或删除操作。

继续更新前，还需满足：

·已获取目标 Tool 的 ToolId。

·如果需要更新 CustomConfiguration.Image，确认镜像地址包含 tag。

·如果需要调整 NetworkConfiguration，请在更新后通过 agr tool get 回查 NetworkConfiguration 字段，确认目标网络配置已经生效。

三、可更新项

更新请求只接受 ToolId 作为目标标识，不提供修改 ToolName 或 ToolType 的参数。如需变更这两个属性，请新建 Tool 并迁移使用方。

四、执行更新

更新描述、网络模式和标签：

TOOL_ID="<tool-id>"agr tool update "$TOOL_ID" \\ –description "用于日报生成任务的 Code Interpreter Tool" \\ –network-configuration '{"NetworkMode":"PUBLIC"}' \\ –tags '[{"Key":"env","Value":"test"},{"Key":"owner","Value":"alice"}]' \\ -o json

清空全部标签：

agr tool update "$TOOL_ID" –tags '[]' -o json

如果需要一次性更新 CustomConfiguration 或其他请求字段，可准备完整请求体后通过 –request 提交：

{ "ToolId": "<tool-id>", "Description": "用于日报生成任务的 Code Interpreter Tool", "NetworkConfiguration": { "NetworkMode": "PUBLIC" }, "CustomConfiguration": { "Image": "ccr.ccs.tencentyun.com/example/report-runner:v2", "ImageRegistryType": "system", "Command": [ "/app/server" ], "Args": [ "–listen=:8080" ], "Env": [ { "Name": "APP_ENV", "Value": "prod" } ], "Ports": [ { "Name": "http", "Port": 8080, "Protocol": "TCP" } ], "Resources": { "CPU": "2", "Memory": "4Gi" }, "Probe": { "HttpGet": { "Path": "/healthz", "Port": 8080, "Scheme": "HTTP" }, "ReadyTimeoutMs": 30000, "ProbeTimeoutMs": 1000, "ProbePeriodMs": 3000, "SuccessThreshold": 1, "FailureThreshold": 3 } }}

agr tool update "$TOOL_ID" –request @tool-update.json -o json

五、验证结果

更新提交后，查询 Tool 确认目标字段已生效：

agr tool get "$TOOL_ID" -o json

建议至少核对以下字段：

·Description

·NetworkConfiguration.NetworkMode

·Tags

·CustomConfiguration

六、回滚与重试

·如果更新后的配置不符合预期，使用上一次确认可用的参数重新执行 agr tool update，或重新提交已验证的请求体。

·如果请求超时，先执行 agr tool get "$TOOL_ID" -o json 确认当前状态，再决定是否重试。

七、删除 Sandbox Tool

删除不再使用的 Sandbox Tool。删除完成后，该 Tool 不再可查询或使用。

八、前提条件

删除前确认该 Tool 下没有活动实例：

TOOL_ID="<tool-id>"agr instance list –tool-id "$TOOL_ID" -o json

判断结果：

·Data.Items 为空时，可以继续删除。

·如果存在 STARTING、RUNNING 或 STOPPING 状态的实例，请先停止或清理这些实例。

·如需只检查运行中实例，可追加 –filters '[{"Name":"Status","Values":["RUNNING"]}]' 再次查询。

九、执行删除

agr tool delete "$TOOL_ID" -o json

十、验证结果

删除后再次查询 Tool：

agr tool get "$TOOL_ID" -o json

当查询返回 ResourceNotFound.SandboxTool 或等价的资源不存在错误时，表示该 Tool 已完成删除。若删除刚提交，查询结果可能短暂延迟，请稍后重试。

十一、回滚与清理

·删除完成后不支持恢复为原 Tool。

·如业务仍需相同配置，请重新创建 Tool，并更新依赖该 Tool 的自动化流程或实例创建脚本。

·如需保留操作记录，请保存响应中的 RequestId 以便后续排查。

十二、Cloud API 参考

如需直接调用 Cloud API，以下为与 CLI 对应的请求示例。

十三、更新请求

POST /Content-Type: application/json

{ "Action": "UpdateSandboxTool", "Region": "ap-guangzhou", "ToolId": "<tool-id>", "Description": "用于日报生成任务的 Code Interpreter Tool", "NetworkConfiguration": { "NetworkMode": "PUBLIC" }, "Tags": [ { "Key": "env", "Value": "test" }, { "Key": "owner", "Value": "alice" } ]}

成功返回：

{ "Response": { "RequestId": "req-update-example" }}

十四、删除请求

POST /Content-Type: application/json

{ "Action": "DeleteSandboxTool", "Region": "ap-guangzhou", "ToolId": "<tool-id>"}

成功返回：

{ "Response": { "RequestId": "req-delete-example" }}

十五、常见错误码

十六、幂等性说明

·agr schema tool.update -o json 与 agr schema tool.delete -o json 均显示 Idempotency: none。

·如果请求超时，先通过 agr tool get 查询当前状态，再决定是否重试。

·重复删除已不存在的 Tool 时，通常返回资源不存在错误，不应视为删除成功的替代信号。

十七、相关文档

·创建沙箱工具

·查询沙箱工具

·工具类型说明

·管理 Sandbox Tool 标签