Agent Runtime 代码执行

注意：说明：

注意：在运行中的 Sandbox 实例内执行代码时，优先使用 agr instance code run。如需在应用内长期集成代码执行或复用执行上下文，请使用 E2B SDK 或参考数据面 API 文档。

二、开始前准备

·已创建并启动可用的 Sandbox 实例。

·已安装 agr CLI，并准备实例 ID。

export INSTANCE_ID="sbx-xxxxxxxx"

三、使用 agr CLI 执行代码

agr instance code run 是命令行主路径，支持直接传入代码字符串、从文件读取和管道输入三种方式。

四、支持的语言

通过 -l 或 –language 指定语言：

五、输出格式

·非流式模式：-o json，返回完整结构化 JSON。

·流式模式：–stream，搭配 -o text 或 -o ndjson。

·–stream 与 -o json 不兼容。

六、方式一：直接传入代码字符串

agr instance code run "$INSTANCE_ID" \\ -c "result = 1 + 2 + 3\\nprint(f'Result: {result}')" \\ -l python \\ -o json

命令返回 agr.v1 JSON envelope。成功时 Status 为 succeeded，Data 包含执行结果对象；失败时 Status 为 failed，通过 Failure.Code 标识错误原因（详情请参见 错误处理）。

七、方式二：从文件读取代码

agr instance code run "$INSTANCE_ID" \\ -f ./script.py \\ -l python \\ -o json

支持多文件同时传入：

agr instance code run "$INSTANCE_ID" \\ -f ./setup.py -f ./main.py \\ -l python \\ -o json

八、方式三：从标准输入读取代码

cat <<'PY' | agr instance code run "$INSTANCE_ID" -l python -o jsonimport jsondata = {"status": "ok", "value": 42}print(json.dumps(data, indent=2))PY

九、指定其他语言

执行 JavaScript：

agr instance code run "$INSTANCE_ID" \\ -c "const result = [1,2,3].reduce((a,b) => a+b, 0); console.log(result)" \\ -l javascript \\ -o json

执行 Bash：

agr instance code run "$INSTANCE_ID" \\ -c "echo Hello from sandbox && uname -a" \\ -l bash \\ -o json

十、流式输出

实时输出执行过程，适合长时间运行的任务：

agr instance code run "$INSTANCE_ID" \\ -c "import time\\nfor i in range(5):\\n print(f'Step {i}')\\n time.sleep(1)" \\ -l python \\ –stream \\ -o ndjson

–stream 与 -o json 不兼容，流式模式下需搭配 -o ndjson 或 -o text 使用。

十一、使用临时实例

无需事先创建实例，直接在命令中指定 Tool 并自动创建临时实例：

agr instance code run \\ –create-temp-instance \\ –tool-id "tool-xxxxxxxx" \\ –cleanup always \\ -c "print('Running in temp instance')" \\ -l python \\ -o json

–cleanup 控制临时实例的清理策略：

也可以通过 Tool 名称指定：

agr instance code run \\ –create-temp-instance \\ -t "my-tool-name" \\ –cleanup success \\ -c "print('Hello')" \\ -l python \\ -o json

十二、程序化集成与上下文能力

如需将代码执行能力嵌入应用服务、Notebook 工作流或长期运行任务，建议使用程序化入口，而不是直接将本页的 CLI 命令改写成服务端调用。

十三、何时继续使用 CLI

以下场景优先使用 agr instance code run：

·命令行调试或一次性验证。

·Shell 脚本、CI 任务和运维自动化。

·结合临时实例执行短时任务并在结束后清理资源。

十四、何时使用程序化入口

以下场景更适合程序化接入：

·需要在应用内发起代码执行请求。

·需要复用执行上下文，在多次调用之间保留变量状态或工作目录。

·需要通过 SDK 继续访问文件、进程或其他实例内能力。

当前 agr instance code run 公开命令面未提供创建或复用执行上下文的参数。如需此类能力，请改用以下文档：

·用 E2B SDK 跑代码：最短可运行的应用内集成路径。

·沙箱访问 Token：了解实例级访问凭证的获取、校验和清理方式。

注意：说明：

注意：本页聚焦 CLI 主路径，不展开数据面 HTTP 请求示例。程序化接入时，请优先使用已公开的 SDK 或参考数据面 API 文档中的接口定义与鉴权约定。

十六、CLI 错误码

CLI 错误输出示例：

{ "SchemaVersion": "agr.v1", "Command": "instance.code.run", "Status": "failed", "Data": null, "Failure": { "Code": "MISSING_INSTANCE", "Kind": "user", "Message": "instance not found or not accessible", "Hint": "Verify the instance ID and ensure it is in Running state.", "Retryable": false }, "Meta": { "Backend": "cloud", "DurationMs": 320 }}

十七、清理资源

执行完成后，及时删除不再使用的 Sandbox 实例以释放资源。

十八、删除实例

agr instance delete "$INSTANCE_ID" -o json

命令返回 agr.v1 JSON envelope，Data 输出类型为 DeleteResult，包含删除计数和 ID 列表。成功时 Status 为 succeeded；部分失败时 Status 为 partial，Failure.Code 为 PARTIAL_DELETE_FAILED。

十九、忽略不存在的实例

如果实例可能已被其他流程清理，使用 –ignore-not-found 避免报错：

agr instance delete "$INSTANCE_ID" –ignore-not-found -o json

20、批量删除

支持一次删除多个实例：

agr instance delete "sbx-instance1" "sbx-instance2" "sbx-instance3" -o json

21、验证清理完成

确认实例已不存在：

agr instance get "$INSTANCE_ID" -o json

如果返回 INSTANCE_NOT_FOUND 错误，说明实例已成功删除。