AI 原生开放教材

外观

BabyAgent - 后端工程师的 AI Agent 教学项目 (Go 语言版)课时教程·中文原文 ↗仓库 ↗

第八章：沙盒与安全防御（Guardrails） ​

欢迎来到第八章！在前面的章节中，我们已经构建了一个功能完善的 AI Agent，具备了工具调用、上下文管理、记忆系统和 RAG 能力。

然而，当 Agent 能够执行命令、读写文件时，安全性就变得至关重要。本章介绍如何为 Agent 设计安全防护机制，包括 Docker 沙盒隔离和人工确认机制。

🎯 你将学到什么 ​

  1. Docker 沙盒隔离：在容器中运行 bash 命令，保障本地环境安全
  2. 智能工具选择：自动检测 Docker 可用性，优雅降级到普通 bash
  3. 人工确认（Human-in-the-loop）：在执行危险命令前请求用户确认
  4. 确认状态管理：Allow/Reject/Always Allow 三种确认选项
  5. Context 取消机制：用户按 ESC 提前终止 Agent Loop

🛠 核心功能 ​

1. Docker 沙盒隔离 ​

问题：Agent 执行的 bash 命令可能对本地系统造成破坏性影响。

解决方案：使用 Docker 容器隔离执行环境，限制命令的影响范围。

沙盒架构：

┌─────────────────────────────────────────────────┐
│  Host Machine                                    │
│                                                  │
│  ┌────────────────────────────────────────────┐ │
│  │  Docker Container: babyagent-sandbox       │ │
│  │  Image: alpine:3.19                        │ │
│  │                                            │ │
│  │  /workspace (mounted)  ←→  Project Dir    │ │
│  │                                            │ │
│  │  $ bash commands execute here              │ │
│  └────────────────────────────────────────────┘ │
│                                                  │
│  docker exec container sh -c "command"           │
└─────────────────────────────────────────────────┘

核心特性：

  • 工作区隔离：每个工作区使用独立的容器（容器名包含项目名称）
  • Lazy Initialization：首次使用时自动启动容器
  • 自动创建：容器不存在时自动创建并配置
  • 卷挂载：将项目目录挂载到容器的 /workspace
  • 优雅降级：Docker 不可用时自动切换到普通 bash
  • 保持运行：容器使用 sleep infinity 保持运行状态

容器命名规则：

  • 项目目录 /home/user/project-a → 容器名 babyagent-sandbox-project-a
  • 项目目录 /home/user/project-b → 容器名 babyagent-sandbox-project-b

这样每个工作区都有独立的沙盒环境，互不干扰。

工具工厂模式：

系统会自动检测 Docker 是否可用：

  • Docker 可用 + 工作目录非空 → 使用 DockerBashTool
  • Docker 不可用或工作目录为空 → 使用普通 BashTool

2. 工具调用确认 ​

问题：Agent 可能执行危险操作（如 rm -rf），需要人工干预。

解决方案：为工具配置确认选项，执行前展示确认框。

┌─────────────────────────────────────────┐
│ 工具确认                                 │
│ bash(cowsay "Hello")                    │
│                                         │
│   ┌─────────────────────────┐           │
│   │   ▶ 允许                │           │
│   │     拒绝                │           │
│   │     始终允许            │           │
│   └─────────────────────────┘           │
│                                         │
│ ↑↓ 选择  Enter 确认  Esc 拒绝           │
└─────────────────────────────────────────┘

三种确认选项：

  • 允许：执行本次工具调用
  • 拒绝：拒绝本次调用，终止 Agent Loop
  • 始终允许：执行并记录，当前会话同类工具不再确认

3. 提前终止 Loop（ESC） ​

需求：用户可以随时按 ESC 终止 Agent Loop。

实现机制：

  1. TUI 创建可取消的 context
  2. 用户按 ESC → 发送取消信号
  3. Agent 检测到取消 → 跳过 policies/memory，保存当前状态

📖 代码结构速览 ​

Agent (ch08/agent.go) ​

  • ToolConfirmConfig：工具确认配置
  • alwaysAllowTools：当前会话的"始终允许"记录
  • findTool()：统一的工具查找方法（支持本地和 MCP 工具）
  • RunStreaming()：支持确认和取消的流式请求

Docker Tool (ch08/tool/docker_bash.go) ​

  • DockerBashTool：Docker 容器化 bash 工具
  • ensureSandboxContainer()：确保容器运行（启动或创建）
  • Lazy 初始化：首次使用时启动容器

Tool Factory (ch08/tool/factory.go) ​

  • CreateBashTool()：智能 bash 工具创建函数
  • checkDockerAvailable()：检测 Docker 是否可用
  • 自动选择合适的 bash 工具实现

VO (ch08/vo.go) ​

  • ConfirmationAction：确认动作枚举（Allow/Reject/AlwaysAllow）
  • ToolConfirmationVO：确认请求数据结构
  • MessageTypeToolConfirm：确认消息类型

TUI (ch08/tui/tui.go) ​

  • stateAwaitingConfirmation：等待用户确认状态
  • confirmOptions：确认选项列表
  • selectedConfirmIdx：当前选中的选项索引
  • renderConfirmBox()：渲染确认框 UI

💡 使用示例 ​

运行 TUI ​

bash
go run ./ch08/main

Docker 沙盒示例 ​

首次运行：

你: 列出当前目录的文件

Agent: [检测到 Docker，启动沙盒容器...]
      [创建容器 babyagent-sandbox，镜像 alpine:3.19]

Agent: [在容器中执行命令]
      docker exec babyagent-sandbox sh -c "ls -la"

输出: drwxr-xr-x  workspace/
      -rw-r--r--  main.go
      -rw-r--r--  README.md
      ...

工具确认示例 ​

你: 用 bash 说 hello

Agent: 准备调用 bash 工具

[确认框弹出]
  ┌─────────────────────────────────┐
  │ 工具确认                         │
  │ bash(cowsay "Hello")            │
  │                                 │
  │   ▶ 允许                         │
  │     拒绝                         │
  │     始终允许                     │
  └─────────────────────────────────┘
  │ ↑↓ 选择  Enter 确认  Esc 拒绝    │

[用户按 ↓ 选择"始终允许"，Enter 确认]

Agent: [在容器中执行命令]
      docker exec babyagent-sandbox sh -c "cowsay Hello"

输出: ____
       / Hello \
       --------
        \  /
         \/

[后续 bash 调用不再需要确认]

ESC 取消示例 ​

你: 帮我删除所有日志文件

Agent: 准备调用 bash

[用户按 ESC]

提示: 用户取消了 agent loop，消息已保留。

你: 继续执行删除操作

[Agent 从上次消息继续，不需要重新上下文]

🔧 配置说明 ​

工具确认配置 ​

在 ch08/tui/main.go 中配置需要确认的工具：

  • tool.AgentToolBash：bash 命令需要确认
  • tool.AgentToolWrite：写文件需要确认
  • tool.AgentToolEdit：编辑文件需要确认
  • tool.AgentToolRead：读取文件通常不需要确认

MCP 工具确认 ​

MCP 工具使用完整工具名（如 babyagent_mcp__filesystem__write_file）作为 key 进行配置。

Docker 沙盒配置 ​

默认配置（可在 ch08/tool/docker_bash.go 中修改）：

  • 容器名称：babyagent-sandbox-{项目名}（每个工作区独立）
  • 镜像：alpine:3.19
  • 工作目录：自动挂载当前项目目录到 /workspace

⚠️ 注意事项 ​

  1. Docker 要求：使用 Docker 沙盒需要本地安装并启动 Docker
  2. 容器持久化：容器使用 unless-stopped 重启策略，重启后自动运行
  3. 确认状态与会话绑定：alwaysAllowTools 在 ResetSession() 后清空
  4. ConfirmReject 终止 Loop：拒绝工具调用会返回错误，退出循环

📚 延伸阅读 ​

功能扩展方向 ​

更细粒度的确认策略

  • 按命令前缀：rm* 开头的命令需要确认
  • 按文件路径：修改 /etc/* 文件需要确认
  • 按参数大小：大文件操作需要确认
  • 按时间窗口：第一次调用确认，N 分钟内免确认

审计日志

  • 记录所有工具调用和用户确认决策
  • 便于安全审计和问题排查

权限级别

  • Safe：无需确认（如读取文件）
  • Warning：需要确认（如写入文件）
  • Danger：需要二次确认（如删除操作）

更强大的沙盒

  • 网络隔离：禁止容器访问外网
  • 资源限制：CPU、内存使用限制
  • 只读挂载：某些目录只读挂载，防止篡改

Docker 与容器安全 ​

Docker 安全最佳实践

  • 使用非 root 用户运行容器
  • 限制容器资源（CPU、内存）
  • 只读文件系统
  • 网络隔离与防火墙规则

容器逃逸防护

  • 避免特权模式（--privileged）
  • 谨慎使用卷挂载
  • AppArmor/Seccomp 配置

AI Agent 安全 ​

Prompt Injection：提示词注入攻击与防御

  • 研究案例：indirect prompt injection
  • 防御策略：输入验证、输出清洗、分隔符设计

工具调用安全：限制 Agent 能力范围

  • 白名单/黑名单策略
  • 沙箱执行环境
  • 审计与监控

Human-in-the-Loop：人机协同的安全设计

  • 关键操作人工确认
  • 可解释性与透明度
  • 紧急停止机制

相关工具与框架 ​

  • E2B：专为 AI Agent 设计的沙箱环境
  • Docker Sandboxing：使用 Docker 构建隔离执行环境
  • gVisor：用户空间内核，更强的容器隔离
  • Firecracker：轻量级虚拟机，微秒级启动

推荐资源 ​

  • OWASP LLM Top 10：大语言模型应用的安全风险清单
  • Anthropic Constitutional AI：通过原则约束 AI 行为
  • OpenAI Safety Guidelines：OpenAI 的安全实践指南
  • Claude's Guardrails：Claude 的安全防护机制设计