一、前提条件
·已安装 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
参数说明：
| 参数 | 说明 |
| –tool-name | 沙箱工具的名称，需在当前账号下唯一。 |
| –tool-type | 沙箱工具的类型。这篇使用 code-interpreter，沙箱工具的类型请参见 工具类型说明。 |
| –network-configuration | 网络模式。SANDBOX 模式下沙箱实例仅可访问内部网络。沙箱工具的网络模式请参见 网络模式。 |
| -o json | 以 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 跑代码。