Agent Runtime 查询沙箱工具

一、操作场景

·查看当前账号下已有的 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 和 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 控制分页：

例如，查询第 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

其中：

如果筛选条件较长，建议把 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，同名字段会切换为枚举值：

注意：说明：

注意：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 的顶层字段说明如下：

十八、Data.Pagination 字段

Data.Pagination 用于说明本次返回结果的分页信息：

十九、Data.Items[] 字段

Data.Items 中每个对象表示一个 Tool，常见字段说明如下：

20、CLI 与 API/SDK 字段对照

CLI 输出字段与 Cloud API / SDK 字段并不完全同名。常用映射如下：

21、API/SDK 参考

CLI 已覆盖 Tool 列表查询、分页、按 ToolId 精确查询，以及通过 Filters 传入高级筛选条件等常见场景。只有在你需要把查询逻辑集成到自建控制面、批处理任务或 SDK 程序中时，才需要直接使用 API/SDK。

公开程序化入口建议如下：

如果你需要查看 Cloud API / SDK 的请求体、返回字段或 HTTP 形态，请参考 沙箱工具 API。本页聚焦 agr tool list 主路径，不再单列 REST 代理路径，以免将 Tool 查询和 E2B 兼容实例接口混为一谈。

一个最小的 Cloud API 业务请求体示例如下：

{ "OAEnglishId": "alice", "ToolIds": [ "tool-9f3b2a1c" ], "Offset": 0, "Limit": 20}

22、清理

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，可参考 更新与删除。

23、相关操作

·创建沙箱工具

·管理 Sandbox Tool 标签