在AgentENV中运行Python代码：从拉取模板到执行命令的极简教程-平芜编程栈

在AgentENV中运行Python代码：从拉取模板到执行命令的极简教程

【免费下载链接】AgentENVAgentENV (AENV) is a distributed platform for running agent environments at scale.项目地址: https://gitcode.com/gh_mirrors/age/AgentENV

AgentENV（AENV）是一个用于大规模运行 AI Agent 环境的分布式沙箱平台，基于 Firecracker 微虚拟机，支持快速启动、暂停、快照与分叉。本教程带你用aenvCLI 在5 步之内完成：拉取 Python 模板 → 启动沙箱 → 在沙箱里执行 Python 代码 → 上传下载文件 → 清理资源，全程无需编写任何示例工程。

一、准备工作：部署 AgentENV 并安装 aenv CLI

运行前需要一台满足以下条件的 Linux 服务器（详见 quickstart.md）：

要求	说明
内核版本	Linux 6.8 及以上
虚拟化	可访问`/dev/kvm`（Firecracker 微虚拟机）

方式 A：安装脚本（推荐，同时装好服务器和 CLI）

curl -fsSL https://raw.githubusercontent.com/kvcache-ai/AgentENV/main/scripts/install.sh | sudo bash sudo systemctl start aenv

方式 B：Docker 部署

docker pull ghcr.io/kvcache-ai/aenv-server:latest docker run -d --name aenv-server --privileged -v /dev:/dev -p 8000:8000 ghcr.io/kvcache-ai/aenv-server:latest

安装完 CLI 后（方式 A 已包含），用 API Key 完成认证：

aenv auth # AENV server URL [http://localhost:8000]: http://127.0.0.1:8000 # API key: <粘贴首次启动生成的密钥>

💡 Key 的获取位置：本机安装为sudo cat /var/lib/aenv/secrets/api-key，Docker 方式为docker exec aenv-server cat /workspace/env/secrets/api-key。

二、一键拉取 Python 模板：把镜像变成可秒启的沙箱

模板（Template）是 AgentENV 的核心概念：它把 OCI 镜像预先"烘焙"成可复用的启动快照，之后的每次aenv start都能以毫秒级速度拉起沙箱。

只需一条命令导入官方 Python 3.12 镜像并命名为python：

aenv pull python:3.12-slim --name python

该命令默认会阻塞等待构建完成，执行结束后模板即处于就绪状态。相关文档见 templates.md，实现位于 pull.rs。

三、启动沙箱：获取 Sandbox ID

使用-d参数以分离模式启动，把返回的沙箱 ID 存入变量，方便后续执行命令：

SANDBOX_ID="$(aenv start python -d)"

不加-d时，aenv start会直接进入交互式 Shell。其他常用参数（详见 sandboxes.md）：

--timeout <秒>：设置沙箱存活时间，默认 300 秒，到期自动暂停（Auto-Eviction）
--volume <挂载路径=卷名>：挂载持久化卷

四、在沙箱中执行 Python 代码

aenv exec可在沙箱内运行任意一次性命令并流式回传输出，退出码与远端命令一致。本教程的示例程序直接内联在命令中，无需任何源文件：

aenv exec "$SANDBOX_ID" python -c ' from statistics import mean temperatures = [21.5, 23.0, 22.4, 24.1] print(f"average temperature: {mean(temperatures):.2f} C") '

预期输出：

average temperature: 22.75 C

🎉 至此，一个独立的 Python 运行环境就跑起来了。若远端命令的参数与aenv自身参数冲突，可在命令前加--转义（如aenv exec "$SANDBOX_ID" -- mycmd --timeout 10）。命令实现见 exec.rs。

五、进阶：交互式连接与文件传输

操作	命令	说明
交互式 Shell	`aenv connect "$SANDBOX_ID"`	附加快照式终端，沙箱已暂停会自动恢复
上传文件	`aenv upload "$SANDBOX_ID" ./app.py /workspace/app.py`	自动创建缺失的远程目录
下载文件	`aenv download "$SANDBOX_ID" /workspace/result.txt ./`	结果回传本地
暂停 / 恢复	`aenv pause`/`aenv resume`	暂停立即释放 CPU 和内存

对于真实项目，典型工作流是：上传代码 →exec运行 →download取回结果。详细参数说明见 working.md。

六、清理资源：删除沙箱与模板

用完即删，保持环境干净：

aenv delete "$SANDBOX_ID" # 终止并删除沙箱 aenv template delete python # 删除 Python 模板

七、总结与延伸阅读

步骤	命令	作用
1️⃣ 拉模板	`aenv pull python:3.12-slim --name python`	镜像 → 可秒启模板
2️⃣ 启沙箱	`SANDBOX_ID="$(aenv start python -d)"`	毫秒级启动
3️⃣ 跑代码	`aenv exec "$SANDBOX_ID" python -c '...'`	流式执行输出
4️⃣ 清理	`aenv delete`+`aenv template delete`	释放资源