文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>Agent Runtime>操作指南>沙箱管理>更新与删除

更新与删除

最近更新时间：2026-05-27 20:38:30

我的收藏

本页目录：

通过 agr CLI 更新已有 Sandbox Tool 的描述、网络配置、标签或默认自定义容器配置，或删除不再使用的 Tool。如果更新项没有对应的单独 CLI flag，可通过 --request 提交完整请求体。Cloud API 可作为自动化系统的补充入口。

更新 Sandbox Tool

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

前提条件

使用以下命令确认 agr CLI 已可用且已加载配置与凭证：
agr version
agr 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 字段，确认目标网络配置已经生效。

可更新项

更新方式
可更新内容
说明
CLI 参数
Description、NetworkConfiguration、Tags、CustomConfiguration
agr tool update 支持 --description、--network-configuration、--tags、--custom-configuration。
--request 完整请求体
Description、NetworkConfiguration、Tags、CustomConfiguration
适合一次性提交完整更新请求。
Cloud API
Description、NetworkConfiguration、Tags、CustomConfiguration
对应 UpdateSandboxTool。
更新请求只接受 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"
  }
}

常见错误码

错误码
触发场景
处理建议
ResourceNotFound.SandboxTool
更新或删除的 Tool 不存在，或当前账号无权访问该 Tool。
执行 agr tool get <tool-id> -o json 确认 ToolId 是否正确。
ResourceInUse.SandboxTool
删除时该 Tool 仍有关联中的实例。
执行 agr instance list --tool-id <tool-id> -o json 检查并清理活动实例后重试。
UnsupportedOperation.SandboxTool
请求的更新方式或字段组合不受当前 Tool 支持。
收敛为文档中列出的可更新字段，并重新检查 NetworkConfiguration、Tags 或 CustomConfiguration 的参数组合。
InvalidParameter / InvalidParameterValue.*
请求字段组合不合法，例如网络模式、镜像或请求体格式不符合要求。
核对 NetworkConfiguration、CustomConfiguration 等字段后重新提交。

幂等性说明

agr schema tool.update -o json 与 agr schema tool.delete -o json 均显示 Idempotency: none。
如果请求超时，先通过 agr tool get 查询当前状态，再决定是否重试。
重复删除已不存在的 Tool 时，通常返回资源不存在错误，不应视为删除成功的替代信号。

相关文档

创建沙箱工具
查询沙箱工具
工具类型说明
管理 Sandbox Tool 标签

中国站