AI Agents · 课时

基于 Docker 的智能体沙箱

Q: 「基于 Docker 的智能体沙箱」这节课中我会学到什么？

启动一次性容器来执行智能体生成的代码 你通过在浏览器中直接运行的动手代码来练习 AI Agents，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

启动一次性容器来执行智能体生成的代码

基于 Docker 的智能体沙箱 是 CoddyKit 上的免费 AI Agents 课时。这是第 1 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 AI Agents 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 AI Agents 课程共包含 4 节课。

代理为什么需要沙箱

当代理执行由 LLM 编写的代码时，这些代码是不受信任的。它们可能会尝试读取敏感文件、建立出站连接或消耗无限的资源。

沙箱会隔离代码执行，因此无论代码执行什么操作，造成的损害都能被限制在沙箱内。

Docker 作为沙箱层

Docker 容器提供轻量级的操作系统级隔离。每个代码片段都在一个全新的容器中运行，并受到明确的资源上限和网络限制。

docker Python SDK 允许您在代理内部以编程方式创建和销毁容器。

import docker

client = docker.from_env()
print(client.version()['Version'])

基本容器运行

client.containers.run() 启动容器、执行命令，并以字节形式返回输出。设置 auto_remove=True 会在容器退出后将其清理。

import docker

client = docker.from_env()

output = client.containers.run(
    'python:3.12-slim',
    'python -c "print(2 + 2)"',
    auto_remove=True
)

print(output.decode())  # '4'

内存和 CPU 限制

如果没有限制，失控的脚本可能耗尽主机内存。传入 mem_limit 和 nano_cpus 以限制资源使用量。

如果进程超出 mem_limit，容器会因 OOM 被终止，并引发异常。

output = client.containers.run(
    'python:3.12-slim',
    'python -c "x = [0]*10**8"',   # tries to allocate ~800 MB
    mem_limit='256m',
    nano_cpus=1_000_000_000,        # 1 CPU
    auto_remove=True
)
# Raises docker.errors.ContainerError if OOM-killed

禁用网络

设置 network_disabled=True 可阻止容器发起任何出站或入站网络调用——即使 DNS 查询也会失败。这样可以阻止数据外泄和命令与控制回调。

output = client.containers.run(
    'python:3.12-slim',
    'python -c "import urllib.request; urllib.request.urlopen(\"http://example.com\")"',
    network_disabled=True,
    auto_remove=True
)
# Raises ContainerError: network unreachable

执行超时

沙盒中的无限循环会永远阻塞您的代理。向 containers.run() 传入以秒为单位的 timeout，这样 Docker 就会在截止时间后终止容器。

import docker
from docker.errors import ContainerError

client = docker.from_env()

try:
    output = client.containers.run(
        'python:3.12-slim',
        'python -c "while True: pass"',
        mem_limit='256m',
        network_disabled=True,
        auto_remove=True,
        timeout=30
    )
except Exception as e:
    print(f'Sandbox timeout or error: {e}')

完整沙盒辅助函数

将所有设置封装到可复用的函数中，就能轻松地从代理工具中调用。返回标准输出和状态标志，以便代理处理失败情况。

import docker

client = docker.from_env()

def run_in_sandbox(code: str, timeout: int = 30) -> dict:
    cmd = f'python -c "{code.replace(chr(34), chr(39))}"'
    try:
        out = client.containers.run(
            'python:3.12-slim',
            cmd,
            mem_limit='256m',
            nano_cpus=500_000_000,
            network_disabled=True,
            auto_remove=True,
            timeout=timeout
        )
        return {'success': True, 'output': out.decode()}
    except Exception as e:
        return {'success': False, 'error': str(e)}

挂载临时工作区

如果代码需要读取输入文件或写入输出文件，请将临时主机目录挂载到容器中。对工作区使用带有 'rw' 模式的 volumes，不要挂载其他内容。

import tempfile, os

with tempfile.TemporaryDirectory() as tmpdir:
    # Write input data
    with open(os.path.join(tmpdir, 'data.txt'), 'w') as f:
        f.write('hello sandbox')

    output = client.containers.run(
        'python:3.12-slim',
        'python -c "print(open(\"/workspace/data.txt\").read())"',
        volumes={tmpdir: {'bind': '/workspace', 'mode': 'rw'}},
        mem_limit='256m',
        network_disabled=True,
        auto_remove=True
    )
    print(output.decode())

只读文件系统

设置 read_only=True，将容器的根文件系统挂载为只读。代码只能写入明确挂载的卷。这样可以阻止代码写入镜像内的 /etc、/usr 或其他敏感路径。

import tempfile

with tempfile.TemporaryDirectory() as tmpdir:
    output = client.containers.run(
        'python:3.12-slim',
        'python -c "open(\"/output/result.txt\",\"w\").write(str(1+1))"',
        volumes={tmpdir: {'bind': '/output', 'mode': 'rw'}},
        read_only=True,
        mem_limit='256m',
        network_disabled=True,
        auto_remove=True
    )
    print(open(f'{tmpdir}/result.txt').read())  # '2'

将沙盒集成到代理工具中

将沙盒运行器注册为 LLM 可以调用的工具。代理生成代码，工具在隔离环境中执行代码，然后将输出传回下一次推理步骤。

tools = [
    {
        'type': 'function',
        'function': {
            'name': 'execute_python',
            'description': 'Run a Python snippet in an isolated Docker sandbox.',
            'parameters': {
                'type': 'object',
                'properties': {
                    'code': {'type': 'string', 'description': 'Python code to execute.'}
                },
                'required': ['code']
            }
        }
    }
]

def handle_tool_call(name, args):
    if name == 'execute_python':
        return run_in_sandbox(args['code'])

错误处理与清理

如果 Docker 守护进程未运行，或镜像尚未缓存，容器可能无法启动。始终处理 docker.errors.DockerException，并确保即使发生异常也能清理容器。

from docker.errors import DockerException, ImageNotFound

def safe_run(code: str) -> dict:
    try:
        return run_in_sandbox(code)
    except ImageNotFound:
        # Pull the image first
        client.images.pull('python:3.12-slim')
        return run_in_sandbox(code)
    except DockerException as e:
        return {'success': False, 'error': f'Docker unavailable: {e}'}
    except Exception as e:
        return {'success': False, 'error': str(e)}

哪项沙盒设置对于防止数据外泄最重要？

代理沙盒必须阻止执行的代码将窃取的数据发送到外部服务器。哪个 Docker 参数可以直接阻止出站网络访问？

Docker 沙盒回顾

基于 Docker 的沙盒通过结合内存和 CPU 限制、网络隔离、执行超时和只读文件系统，为代理提供安全的执行环境。

将这些设置封装到可复用的辅助函数中，并将其作为代理工具公开，就能让 LLM 安全地运行生成的代码，而不会危及主机系统。

常见问题解答

「基于 Docker 的智能体沙箱」课时是免费的吗？

是的 — 「基于 Docker 的智能体沙箱」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 AI Agents 课程的其余内容，请升级到 CoddyKit PRO。 AI Agents 课程共包含 4 节课。

「基于 Docker 的智能体沙箱」这节课中我会学到什么？

启动一次性容器来执行智能体生成的代码你通过在浏览器中直接运行的动手代码来练习 AI Agents，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 AI Agents 需要有经验吗？

无需任何先前经验。CoddyKit 上的 AI Agents 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 1 节课，共 4 节。

「基于 Docker 的智能体沙箱」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 AI Agents 课中编写并运行代码吗？

能。每节 AI Agents 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 AI Agents