本文介绍如何在 5 分钟内完成首个沙箱的创建、运行和清理。您将准备一个
code-interpreter Tool，基于该 Tool 启动沙箱 Instance，执行一段 Python 代码并验证执行结果，最后清理试用资源。完成本流程后，您可以确认 agr CLI、认证配置和代码执行链路是否正常工作。步骤概览
操作步骤 | 说明 |
准备工作 | 安装 agr CLI，确认认证配置可用。 |
步骤一：准备可用 Tool | 复用已有 Tool，或创建一个临时 code-interpreter Tool。 |
步骤二：创建沙箱实例 | 基于 Tool 启动一个超时时间为 300 秒的 Instance。 |
步骤三：执行 Python 代码 | 在 Instance 中运行 Python 代码并查看返回结果。 |
步骤四：验证结果 | 确认 Instance 状态正常，代码执行结果符合预期。 |
步骤五：清理试用资源 | 删除 Instance；如果使用了临时 Tool，再删除该 Tool。 |
准备工作
已安装
agr CLI。安装方式请参见 安装与配置。已完成 CLI 认证配置，并具备创建 Tool 和启动 Instance 的权限。
执行以下命令确认 CLI 已安装：
agr version
预期结果：
返回
agr version <commit>，表示 CLI 已正确安装。步骤一：准备可用 Tool
创建 Instance 前需要先指定一个 Tool。如果您已有可用的
code-interpreter Tool，直接记录其 ToolId，然后跳到步骤二；如果您是首次使用，请执行以下命令创建一个临时 Tool：agr tool create \\--tool-name "quickstart-code-<timestamp>" \\--tool-type code-interpreter \\--network-configuration '{"NetworkMode":"SANDBOX"}' \\-o json --non-interactive
参数说明：
参数 | 说明 |
--tool-name | Tool 名称，需在当前账号下唯一。建议使用带时间戳的名称以避免冲突。 |
--tool-type | Tool 类型。本文使用 code-interpreter。 |
--network-configuration | 网络配置。 SANDBOX 模式下 Instance 仅可访问内部网络。 |
-o json | 以 JSON 格式输出结果，便于提取字段。 |
--non-interactive | 跳过交互式确认，适用于脚本和自动化场景。 |
示例响应（关键字段节选）：
{"SchemaVersion": "agr.v1","Command": "tool.create","Status": "succeeded","Data": {"ToolId": "sdt-xxxxxxxx","RequestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}}
请记录
Data.ToolId，后续步骤需要使用该值。步骤二：创建沙箱实例
执行以下命令，基于步骤一获取的
ToolId 创建 Instance：agr instance create \\--tool-id <tool-id> \\--timeout 300s \\-o json --non-interactive
参数说明：
参数 | 说明 |
--tool-id | 步骤一中记录的 Tool ID。 |
--timeout | Instance 超时时间。超时后 Instance 将自动停止。本文使用 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 时，表示 Instance 已启动。CLI 输出中还会返回嵌套的 Data.Instance 对象，后续步骤只需记录顶层 Data.InstanceId 即可。步骤三：执行 Python 代码
Instance 启动后，执行以下命令运行一段 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 表示执行无异常。步骤四：验证结果
执行以下命令查看 Instance 当前状态：
agr instance get <instance-id> -o json --non-interactive
若返回
Data.Status 为 RUNNING，说明 Instance 仍处于运行状态，可以继续接收请求。结合步骤三的执行结果，按以下标准确认本次试用成功：
验证项 | 预期结果 |
Instance 状态 | agr instance get 返回 Data.Status 为 RUNNING。 |
代码执行状态 | agr instance code run 返回 Status 为 succeeded。 |
执行输出 | Data.Stdout 包含 Result: 6。 |
步骤五：清理试用资源
试用结束后，建议立即删除本次创建的 Instance 和临时 Tool，避免资源持续占用。
删除 Instance
执行以下命令：
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}"]}}
确认 Instance 已停止
执行以下命令确认状态：
agr instance get <instance-id> -o json --non-interactive
如果返回
Data.Status 为 STOPPED，表示 Instance 已完成清理。删除临时 Tool
如果步骤一创建了临时 Tool，请在 Instance 状态变为
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}"]}}
说明：
如果删除 Tool 时返回“仍有实例处于活跃状态”的提示，说明 Instance 状态尚未变为
STOPPED。请等待数秒后重新执行 agr instance get 确认状态，再重试删除。后续操作
如需长期复用同一套启动配置，请参见 创建沙箱工具（通过 CLI）。
如需了解 Instance 的完整状态流转（暂停、恢复、超时），请参见 实例生命周期。
如需通过 SDK 接入相同能力，请参见 用 E2B SDK 跑代码。
