本文介绍如何通过 agr CLI 在 5 分钟内创建并运行第一个沙箱：准备一个
code-interpreter 沙箱工具，基于该沙箱工具启动沙箱实例，执行一段 Python 代码并验证执行结果，最后清理试用资源。完成后，您将掌握使用 agr CLI 创建、运行和删除沙箱的基本流程。前提条件
已安装
agr CLI。安装方式请参见 安装与配置。已完成 CLI 认证配置，并具备创建 Tool 和启动 Instance 的权限。
执行以下命令确认 CLI 已安装：
agr version
预期结果：返回
agr version <commit>，表示 CLI 已正确安装。步骤概览
操作步骤 | 说明 |
步骤一：准备可用的沙箱工具 | 复用已有沙箱工具，或创建一个临时 code-interpreter 沙箱工具。 |
步骤二：创建沙箱实例 | 基于沙箱工具启动沙箱实例，并确认其进入 RUNNING 状态。 |
步骤三：执行 Python 代码 | 在沙箱实例中运行 Python 代码并查看返回结果。 |
步骤四：验证结果 | 确认沙箱实例状态正常，代码执行结果符合预期。 |
步骤五：清理试用资源 | 删除沙箱实例；如果使用了临时的沙箱工具，再删除该沙箱工具。 |
步骤一：准备可用的沙箱工具
创建沙箱实例前需要先指定一个沙箱工具。如果您已有可用的
code-interpreter 沙箱工具，直接记录其 ToolId，然后跳到步骤二；如果您是首次使用，请执行以下命令创建一个临时的沙箱工具：agr tool create \\--tool-name "quickstart-code-<timestamp>" \\--tool-type code-interpreter \\--network-configuration '{"NetworkMode":"SANDBOX"}' \\-o json --non-interactive
参数说明：
示例响应（关键字段节选）：
{"SchemaVersion": "agr.v1","Command": "tool.create","Status": "succeeded","Data": {"ToolId": "sdt-xxxxxxxx","RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}}
参数 | 说明 |
"ToolId": "sdt-xxxxxxxxxx" | 新建沙箱工具的唯一标识，后续查询工具、基于工具创建实例时使用 |
"RequestId": "xxxxxxxxxx-..." | 本次请求的追踪标识，排查问题、查日志或联系支持时使用 |
命令执行成功后，请记录返回的
Data.ToolId，后续步骤需要使用该值。步骤二：创建沙箱实例
执行以下命令，基于步骤一获取的
ToolId 启动沙箱实例：agr instance create \\--tool-id <tool-id> \\--timeout 300s \\-o json --non-interactive
参数说明：
参数 | 说明 |
--tool-id | 步骤一中记录的 Tool ID。 |
--timeout | 沙箱实例的超时时间。超时后沙箱实例将自动停止。沙箱实例的最终超时按以下优先级确定：优先使用请求中指定的超时；未指定时使用沙箱工具的默认超时；两者均未设置时使用系统默认 300 秒。本文使用 300s。 |
-o json | 以 JSON 格式输出结果，方便脚本读取。 |
--non-interactive | 以非交互式方式运行，适合自动化脚本。 |
示例响应（关键字段节选）：
{"SchemaVersion": "agr.v1","Command": "instance.create","Status": "succeeded","Data": {"InstanceId": "{instance-id}","ToolId": "{tool-id}","ToolName": "quickstart-code-<timestamp>","Status": "RUNNING","TimeoutSeconds": 300,"ExpiresAt": "{expiry-time}","RequestId": "{request-id}"}}
当
Data.Status 为 RUNNING 时，表示沙箱实例已启动。请记录返回的 Data.InstanceId ，后续步骤需要使用该值。步骤三：执行 Python 代码
沙箱实例成功启动后，执行以下命令运行一段 Python 代码：
agr instance code run <instance-id> \\-c $'result = 1 + 2 + 3\\nprint(f"Result: {result}")' \\-o json --non-interactive
参数说明：
参数 | 说明 |
<instance-id> | 步骤二中获取的 Instance ID。 |
-c | 要执行的代码内容。 |
-o json | 以 JSON 格式输出结果，方便脚本读取。 |
--non-interactive | 以非交互式方式运行，适合自动化脚本。 |
示例响应（关键字段节选）：
{"SchemaVersion": "agr.v1","Command": "instance.code.run","Status": "succeeded","Data": {"Stdout": "Result: 6\\n","Stderr": "","Results": [],"Error": null,"ExecutionCount": 1}}
Data.Stdout 包含代码的标准输出，Data.Error 为 null 表示执行无异常。步骤四：验证结果
执行以下命令查看沙箱实例的当前状态：
agr instance get <instance-id> -o json --non-interactive
若返回
Data.Status 为 RUNNING，说明沙箱实例仍处于运行状态，可以继续接收请求。结合步骤三的执行结果，按以下标准确认本次试用成功：
验证项 | 预期结果 |
沙箱实例的状态 | agr instance get 返回 Data.Status 为 RUNNING。 |
代码执行的状态 | agr instance code run 返回 Status 为 succeeded。 |
执行输出 | Data.Stdout 包含 Result: 6。 |
步骤五：清理试用资源
试用结束后，建议立即删除本次创建的沙箱实例和临时的沙箱工具，避免资源的持续占用。
删除沙箱实例
执行以下命令：
agr instance delete <instance-id> -o json --non-interactive
示例响应（关键字段节选）：
{"SchemaVersion": "agr.v1","Command": "instance.delete","Status": "succeeded","Data": {"Deleted": 1,"Failed": 0,"DeletedIDs": ["{instance-id}"]}}
确认沙箱实例已停止
执行以下命令确认状态：
agr instance get <instance-id> -o json --non-interactive
如果返回
Data.Status 为 STOPPED，表示沙箱实例已完成清理。删除临时的沙箱工具
如果步骤一创建了临时的沙箱工具，请在沙箱实例的状态变为
STOPPED 后执行以下命令：agr tool delete <tool-id> -o json --non-interactive
示例响应（关键字段节选）：
{"SchemaVersion": "agr.v1","Command": "tool.delete","Status": "succeeded","Data": {"Deleted": 1,"Failed": 0,"DeletedIDs": ["{tool-id}"]}}
说明：
如果删除沙箱工具时返回“仍有实例处于活跃状态”的提示，说明沙箱实例的状态尚未变为
STOPPED。请等待数秒后重新执行 agr instance get 确认状态，再重试删除。后续操作
如需长期复用同一套启动配置，请参见 创建沙箱工具（通过 CLI）。
如需了解沙箱实例的完整状态流转（暂停、恢复、超时），请参见 实例生命周期。
如需通过 SDK 接入相同能力，请参见 用 E2B SDK 跑代码。
