Agent Runtime 查询沙箱工具

操作场景
当您需要完成以下任务时，可以使用 agr tool list 查询和过滤 Sandbox Tool：
查看当前账号下已有的 Tool 及其状态。
按状态排查 Tool 创建结果，例如定位 FAILED 原因。
对比不同类型的 Tool 返回值，例如 Browser Tool、Code Interpreter Tool 或其他已创建类型。
按标签、名称或 ToolId 缩小查询范围。
按分页参数分批查看大量 Tool。
前提条件
在执行查询前，建议先完成以下自检。
检查 1：确认 agr CLI 已安装
agr version -o json
如果返回结果中的 Status 为 succeeded，且 Data.Version、Data.Commit 等字段可见，说明当前终端已经可以调用 agr CLI。
检查 2：确认查询凭证和默认地域已就绪
使用以下命令检查当前 shell 的凭证探测结果和默认地域：
agr status -o json
重点关注以下字段：
字段
说明
Data.Auth.SecretId.Present
是否检测到 Cloud API 所需的 SecretId。
Data.Auth.SecretKey.Present
是否检测到 Cloud API 所需的 SecretKey。
Data.Region
当前 CLI 将使用的地域。
Data.ConfigFound
是否检测到 CLI 配置文件。
Data.ConfigLoaded
是否成功加载 CLI 配置文件。
当 Data.Auth.SecretId.Present 和 Data.Auth.SecretKey.Present 都为 true 时，当前 shell 已具备查询 Tool 的云端凭证。任一字段为 false 时，请先通过 agr init --secret-id <id> --secret-key <key>，或在当前环境中注入 TENCENTCLOUD_SECRET_ID 和 TENCENTCLOUD_SECRET_KEY，再执行查询命令。
如果 Data.ConfigFound 或 Data.ConfigLoaded 为 false，说明 CLI 当前没有可用的本地配置文件。此时您仍然可以直接使用环境变量完成查询；如果希望把凭证和默认地域写入 CLI 配置，再执行一次 agr init。
说明：
agr version -o json 用于确认本地 CLI 是否可用，agr status -o json 用于确认当前 shell 的认证状态和默认地域。建议按这个顺序完成前提检查。
检查 3：确认标签筛选前置条件
如果您计划按标签过滤 Tool，请先确认目标 Tool 已经写入对应标签，或先参考 管理 Sandbox Tool 标签 了解标签模型和维护方式。
对系统影响
agr tool list 是只读查询操作。执行该命令不会创建、修改或删除任何 Tool，也不会改变 Sandbox Instance 的运行状态、超时配置或网络设置。您可以在排障、巡检或日常查询时安全执行该命令。
操作步骤
步骤 1：查询全部 Tool
执行以下命令查询当前账号下的 Tool 列表：
agr tool list -o json
执行成功后，返回结果中的 Status 为 succeeded，具体 Tool 数据位于 Data.Items。
示例输出如下：
{
  "SchemaVersion": "agr.v1",
  "Command": "tool.list",
  "Status": "succeeded",
  "Data": {
    "Items": [
      {
        "ToolId": "sdt-2q7x8n4m",
        "ToolName": "demo-browser-tool",
        "ToolType": "browser",
        "Status": "ACTIVE",
        "StatusReason": "",
        "Persistent": false,
        "DefaultTimeoutSeconds": 300,
        "NetworkConfiguration": {
          "NetworkMode": "PUBLIC"
        },
        "Description": "Browser automation sandbox",
        "Tags": {
          "env": "prod",
          "team": "agent-platform"
        },
        "CreateTime": "2026-05-20T19:54:01+08:00",
        "UpdateTime": "2026-05-20T19:54:01+08:00",
        "RoleArn": "",
        "StorageMounts": null,
        "CustomConfiguration": null,
        "LogConfiguration": null
      }
    ],
    "Pagination": {
      "Offset": 0,
      "Limit": 20,
      "Total": 1,
      "NextCursor": null
    }
  },
  "Failure": null,
  "Warnings": [],
  "Meta": {
    "Backend": "cloud",
    "DurationMs": 96
  }
}
步骤 2：分页查询
agr tool list 使用 --offset 和 --limit 控制分页：
参数
说明
--offset
从第几条记录开始返回。取值不能小于 0。
--limit
本次最多返回多少条记录。取值范围为 1 到 100。
例如，查询第 2 页且每页返回 20 条记录：
agr tool list --offset 20 --limit 20 -o json
执行成功后，可通过 Data.Pagination.Offset、Data.Pagination.Limit 和 Data.Pagination.Total 判断当前页位置和总记录数。
步骤 3：按 ToolId 精确查询
如果您已经知道目标 ToolId，可以使用 --tool-ids 只返回指定 Tool：
agr tool list --tool-ids sdt-2q7x8n4m -o json
也可以重复传入多个 --tool-ids：
agr tool list \\
  --tool-ids sdt-2q7x8n4m \\
  --tool-ids sdt-8p4n2k6q \\
  -o json
按 ToolId 精确查询时，建议只保留 --tool-ids、--offset、--limit 和 --filters 中真正需要的参数，避免把无关筛选条件混入同一条命令。
步骤 4：通过 --filters 传入高级筛选条件
当前版本的 agr tool list 不再提供 --status、--type、--tag、--id 这类独立 flag。需要高级筛选时，请统一通过 --filters 传入 JSON 数组；数组中的每个对象都包含 Name 和 Values 两个字段。
agr tool list --filters '[{"Name":"Tag","Values":["env=prod"]}]' -o json
其中：
字段
说明
Name
过滤条件名称。
Values
过滤值数组。每个过滤条件至少传 1 个值。
如果筛选条件较长，建议把 JSON 放到文件中，再通过 --filters @<file> 或 --request @<file> 传入。
步骤 5：按标签或名称缩小范围
--filters 适合承载标签和名称类筛选条件。以下示例展示当前常见写法。
按标签筛选：
agr tool list --filters '[{"Name":"Tag","Values":["env=prod"]}]' -o json
按 Tool 名称精确匹配：
agr tool list --filters '[{"Name":"tool-name","Values":["demo-browser-tool"]}]' -o json
按 Tool 名称关键字匹配：
agr tool list --filters '[{"Name":"tool-name-like","Values":["browser"]}]' -o json
执行成功后，返回结果中的 Tags 会以 JSON 对象形式展示当前 Tool 的标签键值对。如果您还没有统一标签键名或筛选约定，请先参考 管理 Sandbox Tool 标签。
步骤 6：理解 ToolType 和 Status 的命名层级
CLI 输出中的 Data.Items[].ToolType 和 Data.Items[].Status 直接使用短值或简化状态值，例如：
ToolType：browser、code-interpreter
Status：CREATING、ACTIVE、DELETING、FAILED
如果您改用 Cloud API DescribeSandboxToolList 或对应 SDK 查询同一批 Tool，同名字段会切换为枚举值：
语义
CLI 输出值
Cloud API / SDK 返回值
浏览器型 Tool
browser
SANDBOX_TOOL_TYPE_BROWSER
代码执行型 Tool
code-interpreter
SANDBOX_TOOL_TYPE_CODE_INTERPRETER
可用状态
ACTIVE
SANDBOX_TOOL_STATUS_ACTIVE
失败状态
FAILED
SANDBOX_TOOL_STATUS_FAILED
说明：
agr tool create --tool-type code-interpreter 使用的是 CLI 短值；DescribeSandboxToolList 返回的是 Cloud API / SDK 枚举值。两者指向同一类 Tool，但不要混用。
如需继续了解已公开的 Tool 类型说明，可阅读 Tool 类型。
步骤 7：组合分页与筛选条件
您可以将分页、ToolId 和 Filters 组合使用：
agr tool list \\
  --tool-ids sdt-2q7x8n4m \\
  --filters '[{"Name":"Tag","Values":["env=prod"]}]' \\
  --offset 0 \\
  --limit 20 \\
  -o json
这种方式适合在结果较多时缩小范围并分批查看。
步骤 8：使用 --request 传完整请求体
当筛选条件较多，或您希望把查询参数保存到脚本与 CI 中时，可以直接传入完整请求体：
{
  "ToolIds": [
    "sdt-2q7x8n4m"
  ],
  "Filters": [
    {
      "Name": "Tag",
      "Values": [
        "env=prod"
      ]
    }
  ],
  "Offset": 0,
  "Limit": 20
}
将该 JSON 保存为 tool-query.json 后，可执行：
agr tool list --request @tool-query.json -o json
这种方式适合复用固定查询条件，也能减少 shell 转义带来的错误。
返回结果说明
CLI 顶层字段
agr tool list -o json 的顶层字段说明如下：
字段
说明
SchemaVersion
CLI 输出 schema 版本。
Command
当前执行的命令名。
Status
命令执行状态。成功时为 succeeded。
Data
查询结果主体。
Failure
失败信息。执行成功时为 null。
Warnings
警告信息列表。
Meta
运行元信息，例如后端类型和耗时。
Data.Pagination 字段
Data.Pagination 用于说明本次返回结果的分页信息：
字段
说明
Offset
本次请求使用的偏移量。
Limit
本次请求使用的分页大小。
Total
当前过滤条件下的总记录数。
NextCursor
预留字段，当前返回 null。翻页请继续使用 --offset 和 --limit。
Data.Items[] 字段
Data.Items 中每个对象表示一个 Tool，常见字段说明如下：
字段
说明
ToolId
Tool 唯一标识。
ToolName
Tool 名称。
ToolType
Tool 类型。CLI 返回短值。
Status
当前状态。
StatusReason
状态说明或失败原因。FAILED 场景下通常会返回可直接用于排障的错误信息。
Persistent
是否为持久化 Tool。
DefaultTimeoutSeconds
默认超时时间，单位为秒。未设置时可能为 null。
NetworkConfiguration.NetworkMode
网络模式，例如 PUBLIC 或 SANDBOX。以实际返回值为准。
Description
Tool 描述。
Tags
标签集合。CLI 以 JSON 对象输出。
CreateTime
创建时间。
UpdateTime
最近更新时间。
RoleArn
角色 ARN。未配置时通常为空字符串。
StorageMounts
存储挂载配置列表。
CustomConfiguration
自定义配置。仅在对应 Tool 使用该能力时返回。
LogConfiguration
日志配置。仅在对应 Tool 使用该能力时返回。
CLI 与 API/SDK 字段对照
CLI 输出字段与 Cloud API / SDK 字段并不完全同名。常用映射如下：
CLI 字段
API/SDK 字段
差异说明
Data.Items
SandboxToolSet
语义一致，都是 Tool 列表。
Data.Pagination.Total
TotalCount
CLI 把总数放在分页结构内；API/SDK 单独返回总数。
Data.Items[].ToolType
SandboxToolSet[].ToolType
CLI 使用短值，例如 browser；API/SDK 使用 SANDBOX_TOOL_TYPE_* 枚举。
Data.Items[].Status
SandboxToolSet[].Status
CLI 使用简化状态值，例如 ACTIVE；API/SDK 使用 SANDBOX_TOOL_STATUS_* 枚举。
Data.Items[].Tags
SandboxToolSet[].Tags
CLI 输出为 JSON 对象；API/SDK 输出为 [{"Key":"...","Value":"..."}] 结构。
Data.Items[].StatusReason
公开 API 文档未单独列为业务返回字段
CLI 查询结果里可以直接看到失败原因；编写 API/SDK 自动化时不要假设该字段一定存在。
API/SDK 参考
CLI 已覆盖 Tool 列表查询、分页、按 ToolId 精确查询，以及通过 Filters 传入高级筛选条件等常见场景。只有在您需要把查询逻辑集成到自建控制面、批处理任务或 SDK 程序中时，才需要直接使用 API/SDK。
公开程序化入口建议如下：
类型
入口
说明
Cloud API / 腾讯云 SDK
DescribeSandboxToolList
用于查询 Tool 列表、分页和 Filters。
E2B SDK / E2B HTTP
/sandboxes 系列接口
用于管理沙箱实例，不用于查询 Tool 清单。
如果您需要查看 Cloud API / SDK 的请求体、返回字段或 HTTP 形态，请参考 沙箱工具 API。本页聚焦 agr tool list 主路径，不再单列 REST 代理路径，以免将 Tool 查询和 E2B 兼容实例接口混为一谈。
一个最小的 Cloud API 业务请求体示例如下：
{
  "OAEnglishId": "alice",
  "ToolIds": [
    "tool-9f3b2a1c"
  ],
  "Offset": 0,
  "Limit": 20
}
清理
agr tool list 本身不会创建、修改或删除 Tool，因此如果您只执行了本页中的查询命令，无需额外清理。
如果您为了验证筛选条件而临时创建了测试 Tool，建议在确认结果后立即回收。可以按以下顺序执行：
1. 查询并记录需要回收的 ToolId。
agr tool get <tool-id> -o json
2. 删除测试 Tool。
agr tool delete <tool-id> -o json
3. 再次按 ToolId 查询，观察目标 Tool 是否仍可查询到。
agr tool list --tool-ids <tool-id> -o json
您可以结合 更新与删除 中的删除说明，继续关注后续处理状态。请注意，不建议仅凭单次查询结果判断删除已完全完成，建议稍后再次查询确认目标 Tool 已从列表中移除。
如需继续调整或批量回收 Tool，可参考 更新与删除。
相关操作
﻿创建沙箱工具﻿
﻿管理 Sandbox Tool 标签﻿

字段	说明
`Data.Auth.SecretId.Present`	是否检测到 Cloud API 所需的 `SecretId`。
`Data.Auth.SecretKey.Present`	是否检测到 Cloud API 所需的 `SecretKey`。
`Data.Region`	当前 CLI 将使用的地域。
`Data.ConfigFound`	是否检测到 CLI 配置文件。
`Data.ConfigLoaded`	是否成功加载 CLI 配置文件。

参数	说明
`--offset`	从第几条记录开始返回。取值不能小于 `0`。
`--limit`	本次最多返回多少条记录。取值范围为 `1` 到 `100`。

语义	CLI 输出值	Cloud API / SDK 返回值
浏览器型 Tool	`browser`	`SANDBOX_TOOL_TYPE_BROWSER`
代码执行型 Tool	`code-interpreter`	`SANDBOX_TOOL_TYPE_CODE_INTERPRETER`
可用状态	`ACTIVE`	`SANDBOX_TOOL_STATUS_ACTIVE`
失败状态	`FAILED`	`SANDBOX_TOOL_STATUS_FAILED`

字段	说明
`SchemaVersion`	CLI 输出 schema 版本。
`Command`	当前执行的命令名。
`Status`	命令执行状态。成功时为 `succeeded`。
`Data`	查询结果主体。
`Failure`	失败信息。执行成功时为 `null`。
`Warnings`	警告信息列表。
`Meta`	运行元信息，例如后端类型和耗时。

字段	说明
`ToolId`	Tool 唯一标识。
`ToolName`	Tool 名称。
`ToolType`	Tool 类型。CLI 返回短值。
`Status`	当前状态。
`StatusReason`	状态说明或失败原因。`FAILED` 场景下通常会返回可直接用于排障的错误信息。
`Persistent`	是否为持久化 Tool。
`DefaultTimeoutSeconds`	默认超时时间，单位为秒。未设置时可能为 `null`。
`NetworkConfiguration.NetworkMode`	网络模式，例如 `PUBLIC` 或 `SANDBOX`。以实际返回值为准。
`Description`	Tool 描述。
`Tags`	标签集合。CLI 以 JSON 对象输出。
`CreateTime`	创建时间。
`UpdateTime`	最近更新时间。
`RoleArn`	角色 ARN。未配置时通常为空字符串。
`StorageMounts`	存储挂载配置列表。
`CustomConfiguration`	自定义配置。仅在对应 Tool 使用该能力时返回。
`LogConfiguration`	日志配置。仅在对应 Tool 使用该能力时返回。

查询沙箱工具

本页目录：

操作场景

前提条件

检查 1：确认 `agr` CLI 已安装

检查 2：确认查询凭证和默认地域已就绪

检查 3：确认标签筛选前置条件

对系统影响

操作步骤

步骤 1：查询全部 Tool

步骤 2：分页查询

步骤 3：按 `ToolId` 精确查询

步骤 4：通过 `--filters` 传入高级筛选条件

步骤 5：按标签或名称缩小范围

步骤 6：理解 `ToolType` 和 `Status` 的命名层级

步骤 7：组合分页与筛选条件

步骤 8：使用 `--request` 传完整请求体

返回结果说明

CLI 顶层字段

`Data.Items[]` 字段

CLI 与 API/SDK 字段对照

API/SDK 参考

清理

相关操作

字段	说明
`Name`	过滤条件名称。
`Values`	过滤值数组。每个过滤条件至少传 1 个值。

字段	说明
`Offset`	本次请求使用的偏移量。
`Limit`	本次请求使用的分页大小。
`Total`	当前过滤条件下的总记录数。
`NextCursor`	预留字段，当前返回 `null`。翻页请继续使用 `--offset` 和 `--limit`。

CLI 字段	API/SDK 字段	差异说明
`Data.Items`	`SandboxToolSet`	语义一致，都是 Tool 列表。
`Data.Pagination.Total`	`TotalCount`	CLI 把总数放在分页结构内；API/SDK 单独返回总数。
`Data.Items[].ToolType`	`SandboxToolSet[].ToolType`	CLI 使用短值，例如 `browser`；API/SDK 使用 `SANDBOX_TOOL_TYPE_*` 枚举。
`Data.Items[].Status`	`SandboxToolSet[].Status`	CLI 使用简化状态值，例如 `ACTIVE`；API/SDK 使用 `SANDBOX_TOOL_STATUS_*` 枚举。
`Data.Items[].Tags`	`SandboxToolSet[].Tags`	CLI 输出为 JSON 对象；API/SDK 输出为 `[{"Key":"...","Value":"..."}]` 结构。
`Data.Items[].StatusReason`	公开 API 文档未单独列为业务返回字段	CLI 查询结果里可以直接看到失败原因；编写 API/SDK 自动化时不要假设该字段一定存在。

类型	入口	说明
Cloud API / 腾讯云 SDK	`DescribeSandboxToolList`	用于查询 Tool 列表、分页和 `Filters`。
E2B SDK / E2B HTTP	`/sandboxes` 系列接口	用于管理沙箱实例，不用于查询 Tool 清单。