langchain-docker-sandbox 0.1.1

Custom Docker sandbox backend for Deep Agents framework, providing isolated code execution environments

Deep Agents Docker Sandbox

一个为 Deep Agents 框架提供自定义 Docker 沙盒后端的项目，让 AI Agent 可以在隔离的 Docker 容器中安全地执行代码和操作文件。

项目地址: https://github.com/hxy2321548628/langchain-docker-sandbox

功能特性

• 隔离执行环境：使用 Docker 容器提供安全的代码执行环境
• 完整的文件操作：支持读取、写入、编辑、上传、下载文件
• 命令执行：在沙盒中执行 shell 命令
• 批量文件传输：支持批量上传和下载文件
• 文件搜索：提供目录列表、模式匹配和文本搜索功能
• 易于集成：无缝集成到 Deep Agents 框架

系统要求

• Python 3.13+
• Docker 和 Docker Compose
• DeepSeek API 密钥

快速安装

uv add langchain-docker-sandbox

git安装

1. 克隆仓库：

git clone https://github.com/hxy2321548628/langchain-docker-sandbox
cd langchain-docker-sandbox

2. 安装依赖：

uv sync

3. 配置环境变量：

cp example/.env.example example/.env
# 编辑 example/.env，填入你的 API 密钥

快速开始

1. 启动 Docker 沙盒容器

docker compose up -d

这会启动一个名为 uv-sandbox 的 Docker 容器，使用 astral/uv:python3.13-bookworm-slim 镜像，并将本地的 filesystem/ 目录挂载到容器的 /workspace。

2. 运行示例

cd example
python main.py

示例代码会创建一个 Deep Agent，让它在沙盒中创建并运行一个 "Hello World" Python 脚本。

使用方法

基本 Agent 创建

from deepagents import create_deep_agent
from langchain_docer_sandbox import DockerSandbox

# 创建 Docker 沙盒后端
backend = DockerSandbox(
    container_name="uv-sandbox",
    work_dir="/workspace"
)

# 创建 Deep Agent
agent = create_deep_agent(
    model="deepseek:deepseek-chat",
    backend=backend,
    system_prompt="你是一个拥有沙盒访问权限的编程助手。你可以在沙盒中创建和运行代码。",
)

# 与 Agent 交互
result = agent.invoke({
    "messages": [
        {
            "role": "user",
            "content": "创建一个计算斐波那契数列的 Python 脚本并运行它"
        }
    ]
})

print(result["messages"][-1].content)

DockerSandbox API

执行命令

backend = DockerSandbox(container_name="uv-sandbox", work_dir="/workspace")

# 执行简单命令
result = backend.execute("echo 'Hello from Docker!'")
print(result.output)  # 输出命令结果
print(result.exit_code)  # 退出码

文件操作

# 写入文件
backend.write("hello.py", "print('Hello World!')")

# 读取文件（带行号）
content = backend.read("hello.py")

# 编辑文件
backend.edit("hello.py", "Hello", "你好", replace_all=False)

# 批量上传
backend.upload_files([
    ("script1.py", b"print('script1')"),
    ("script2.py", b"print('script2')"),
])

# 批量下载
files = backend.download_files(["script1.py", "script2.py"])

文件搜索

# 列出目录
files = backend.ls_info("/workspace")

# 模式匹配搜索
py_files = backend.glob_info("*.py", path="/workspace")

# 文本搜索
matches = backend.grep_raw("hello", path="/workspace", glob="*.py")

测试

运行测试套件需要先启动 Docker 沙盒容器：

# 启动容器
docker compose up -d

# 运行所有测试
uv run pytest

# 运行特定测试
uv run pytest test/test_docker_sandbox.py::TestDockerSandboxExecute::test_execute_simple_command

# 查看测试覆盖率
uv run pytest --cov=langchain_docer_sandbox

项目结构

langchain_docker_sandbox/
├── langchain_docer_sandbox.py   # DockerSandbox 后端实现
├── docker-compose.yml            # Docker Compose 配置
├── filesystem/                   # 挂载到沙盒的目录
├── example/                      # 示例代码
│   ├── main.py                   # 示例入口
│   ├── settings.py               # 配置管理
│   └── .env                      # 环境变量
├── test/                        # 测试代码
│   └── test_docker_sandbox.py    # DockerSandbox 测试
├── pyproject.toml                # 项目配置
└── README.md                     # 本文件

配置说明

环境变量

在 example/.env 中配置以下变量：

DEEPSEEK_API_KEY=your-deepseek-api-key
DEEPSEEK_BASE_URL=https://api.deepseek.com
TAVILY_API_KEY=your-tavily-api-key    # 可选，用于搜索功能
DAYTONA_API_KEY=your-daytona-api-key   # 可选

Docker Compose 配置

docker-compose.yml 配置说明：

services:
  uv-sandbox:
    image: astral/uv:python3.13-bookworm-slim  # 基础镜像
    container_name: uv-sandbox                   # 容器名称
    working_dir: /workspace                     # 工作目录
    volumes:
      - ./filesystem:/workspace                 # 挂载本地目录

你可以根据需要修改镜像、工作目录或挂载点。

依赖项

核心依赖：

• deepagents>=0.4.11 - Deep Agents 框架
• docker>=7.1.0 - Docker SDK for Python

开发依赖：

• pytest>=9.0.2 - 测试框架
• dotenv>=0.9.9 - 环境变量加载
• pydantic>=2.12.5, pydantic-settings>=2.13.1 - 配置管理
• ruff>=0.15.6 - 代码格式化和检查

代码风格

项目使用 Ruff 进行代码格式化和检查：

# 检查代码
ruff check .

# 自动修复问题
ruff check --fix .

# 格式化代码
ruff format .

代码规范：

• 行长度：150 字符
• 字符串：双引号
• 导入顺序：标准库 → 第三方 → 第一方 → 本地
• 文档字符串：Google 风格

故障排除

容器无法启动

# 检查 Docker 是否运行
docker ps

# 查看容器日志
docker compose logs uv-sandbox

# 重启容器
docker compose restart

找不到容器错误

确保 Docker 容器名称 uv-sandbox 正确，并且容器正在运行：

docker ps | grep uv-sandbox

测试失败

确保在运行测试前先启动沙盒容器：

docker compose up -d
uv run pytest

贡献

欢迎提交 Issue 和 Pull Request！

• 提交 Issue: GitHub Issues
• 提交 Pull Request: GitHub Pull Requests

在提交代码前，请确保：

1. 通过所有测试：uv run pytest
2. 代码通过格式化检查：ruff check . 和 ruff format .
3. 更新相关文档

许可证

MIT License

参考资料

• Deep Agents 文档
• LangChain 文档
• Docker SDK for Python