AI Agent / 系统课时

设计命令执行与沙箱

设计命令执行与沙箱

本篇解决智能体执行代码、运行命令时的安全边界问题。通过设计命令执行层、异步进程管理和隔离环境,可以让 Agent 完成自动化任务,同时避免误操作影响宿主系统。

学习目标

  • 理解智能体执行命令时需要控制的安全边界
  • 掌握 subprocess、异步进程与输出捕获的设计方式
  • 学会使用工作目录和 Docker 沙箱隔离执行环境

命令执行层的职责划分

智能体中的命令执行模块不是简单调用终端,而是一个受控执行服务。它需要接收 Agent 生成的执行请求,检查权限后启动进程,并将输出、错误和状态反馈给上层规划模块。

一个基础执行链路通常包含请求解析、环境准备、进程启动、输出收集和资源清理几个阶段。执行层需要明确哪些命令允许运行、运行位置在哪里、最多消耗多少时间和资源。

智能体命令执行与沙箱隔离架构图

使用 subprocess 管理同步执行

Python 中常见的命令执行方式是 subprocess。它可以启动外部程序,并获取标准输出和错误输出。

示例中通过超时参数限制执行时间,并将执行结果转换为 Agent 可以理解的数据结构。

python
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)

预期输出

text
{'exit_code': 0, 'stdout': 'Python <VERSION>\n', 'stderr': ''}

实际项目中还需要增加命令白名单、用户权限检查和环境变量过滤,避免 Agent 生成危险操作。

异步进程与实时输出

代码执行任务可能持续较长时间,例如安装依赖、运行测试或构建项目。同步等待会阻塞 Agent,因此需要异步进程模型。

异步执行通常由事件循环管理进程状态,持续读取 stdout 和 stderr,并将增量日志发送给客户端。

设计时需要关注几个边界:

  • 超时后主动终止进程树
  • 限制最大输出大小,避免日志撑爆内存
  • 保存执行 ID,支持查询任务状态

工作目录与资源控制

每次执行都应该绑定独立工作目录,而不是直接操作项目根目录。工作目录可以保存临时文件、依赖缓存和构建产物。

资源控制包括 CPU、内存、磁盘和网络权限。例如测试任务可以访问代码目录,但不应该默认访问宿主机敏感文件。

使用 Docker 建立沙箱

对于需要运行用户代码的 Agent,Docker 是常见隔离方案。执行流程通常是创建临时容器、挂载指定目录、运行命令、收集结果、删除容器。

bash
docker run --rm \
  --memory=<MEMORY_LIMIT> \
  --cpus=<CPU_LIMIT> \
  -v <PATH>:/workspace \
  python:<VERSION> \
  python /workspace/main.py

预期输出

text
程序执行结果或 Python 运行日志

容器参数需要根据业务风险调整。高风险执行场景还应关闭特权模式,限制网络访问,并使用只读挂载。

本课总结

  • 命令执行层需要同时管理功能调用和安全边界。
  • subprocess 适合基础执行,异步进程适合长任务和实时反馈。
  • Docker 沙箱通过隔离文件系统和资源限制降低执行风险。

下一课预告

下一课将继续设计智能体客户端技术栈,规划编辑器、Agent 面板和终端等交互能力。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计命令执行与沙箱

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通