AI Agent / 系统课时
设计命令执行与沙箱
设计命令执行与沙箱
本篇解决智能体执行代码、运行命令时的安全边界问题。通过设计命令执行层、异步进程管理和隔离环境,可以让 Agent 完成自动化任务,同时避免误操作影响宿主系统。
学习目标
- 理解智能体执行命令时需要控制的安全边界
- 掌握 subprocess、异步进程与输出捕获的设计方式
- 学会使用工作目录和 Docker 沙箱隔离执行环境
命令执行层的职责划分
智能体中的命令执行模块不是简单调用终端,而是一个受控执行服务。它需要接收 Agent 生成的执行请求,检查权限后启动进程,并将输出、错误和状态反馈给上层规划模块。
一个基础执行链路通常包含请求解析、环境准备、进程启动、输出收集和资源清理几个阶段。执行层需要明确哪些命令允许运行、运行位置在哪里、最多消耗多少时间和资源。

使用 subprocess 管理同步执行
Python 中常见的命令执行方式是 subprocess。它可以启动外部程序,并获取标准输出和错误输出。
示例中通过超时参数限制执行时间,并将执行结果转换为 Agent 可以理解的数据结构。
import subprocess
def run_command(command: list[str], timeout_seconds: int = 10):
result = subprocess.run(
command,
capture_output=True,
text=True,
timeout=timeout_seconds,
cwd="<PATH>"
)
return {
"exit_code": result.returncode,
"stdout": result.stdout,
"stderr": result.stderr,
}
result = run_command(["python", "--version"])
print(result)预期输出
{'exit_code': 0, 'stdout': 'Python <VERSION>\n', 'stderr': ''}实际项目中还需要增加命令白名单、用户权限检查和环境变量过滤,避免 Agent 生成危险操作。
异步进程与实时输出
代码执行任务可能持续较长时间,例如安装依赖、运行测试或构建项目。同步等待会阻塞 Agent,因此需要异步进程模型。
异步执行通常由事件循环管理进程状态,持续读取 stdout 和 stderr,并将增量日志发送给客户端。
设计时需要关注几个边界:
- 超时后主动终止进程树
- 限制最大输出大小,避免日志撑爆内存
- 保存执行 ID,支持查询任务状态
工作目录与资源控制
每次执行都应该绑定独立工作目录,而不是直接操作项目根目录。工作目录可以保存临时文件、依赖缓存和构建产物。
资源控制包括 CPU、内存、磁盘和网络权限。例如测试任务可以访问代码目录,但不应该默认访问宿主机敏感文件。
使用 Docker 建立沙箱
对于需要运行用户代码的 Agent,Docker 是常见隔离方案。执行流程通常是创建临时容器、挂载指定目录、运行命令、收集结果、删除容器。
docker run --rm \
--memory=<MEMORY_LIMIT> \
--cpus=<CPU_LIMIT> \
-v <PATH>:/workspace \
python:<VERSION> \
python /workspace/main.py预期输出
程序执行结果或 Python 运行日志容器参数需要根据业务风险调整。高风险执行场景还应关闭特权模式,限制网络访问,并使用只读挂载。
本课总结
- 命令执行层需要同时管理功能调用和安全边界。
- subprocess 适合基础执行,异步进程适合长任务和实时反馈。
- Docker 沙箱通过隔离文件系统和资源限制降低执行风险。
下一课预告
下一课将继续设计智能体客户端技术栈,规划编辑器、Agent 面板和终端等交互能力。