# agent-sandbox_playground

**Repository Path**: chetaofeng/agent-sandbox_playground

## Basic Information

- **Project Name**: agent-sandbox_playground
- **Description**:  OpenSandbox Python SDK 示例项目
通过 Python SDK 与 LangGraph 集成，在隔离沙箱中执行代码。核心场景：**创建沙箱 → 写入文件 → 执行代码 → 获取结果 → 清理沙箱**。

- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-07-07
- **Last Updated**: 2026-07-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenSandbox Python SDK 示例项目

通过 Python SDK 与 LangGraph 集成，在隔离沙箱中执行代码。核心场景：**创建沙箱 → 写入文件 → 执行代码 → 获取结果 → 清理沙箱**。

## 技术栈

- **运行时**: Python 3.12 + uv 包管理
- **沙箱服务**: OpenSandbox (Docker/Kubernetes)
- **Agent 框架**: LangGraph（状态机驱动生命周期）
- **LLM 后端**: vLLM / LiteLLM Proxy / OneAPI / Moonshot / MiniMax / Gemini

## 快速开始

### 1. 安装依赖

```bash
uv pip install opensandbox langgraph langchain-openai python-dotenv colorlog
```

### 2. 配置环境变量

```bash
cp .env.intranet .env
# 编辑 .env 填写实际值（SANDBOX_DOMAIN / API_KEY 等）
```

### 3. 启动 OpenSandbox Server（可选，本地开发时）

```bash
opensandbox-server
```

### 4. 运行示例

```bash
# 完整示例（创建 → 写文件 → 流式执行 → 指标 → 清理）
uv run python src/simple/complete_example.py

# 网络策略示例
uv run python src/simple/network_policy.py

# 文件操作示例
uv run python src/simple/file_operations.py

# 错误处理示例
uv run python src/simple/error_handling.py

# LangGraph Agent 示例
uv run python src/simple/agent_langgraph.py
```

## 项目结构

```
src/simple/               # 核心示例脚本
├── complete_example.py   # 完整流程（写文件 + 流式执行 + 指标 + kill）
├── handling.py           # 完整流程（写文件 + 流式执行 + 指标 + 上下文管理）
├── error_handling.py     # 异常处理（Timeout / API Error / Generic Error）
├── network_policy.py     # 出站网络隔离策略
├── file_operations.py    # 文件读写、搜索、删除
├── command_streaming.py  # 命令流式输出
├── sandbox_basics.py     # 沙箱基础创建与生命周期
├── sandbox_pool.py       # 沙箱池管理
├── agent_langgraph.py    # LangGraph 状态机 Agent
├── agent_tool_call.py    # 原生 Tool Call Agent
├── llm_factory.py        # LLM 客户端工厂
├── config.py             # 中央配置入口（load_dotenv + require_env）
└── quickstart.py         # 快速上手

src/shared/              # 共享场景模块
src/utils/               # 工具函数（日志配置）
examples/                # 官方示例（各种语言/框架集成）
docs/                    # 详细文档
```

## 沙箱生命周期

```
create → write_file → run_code → get_metrics → kill/cleanup
                           ↓
                      [失败重试 ≤2 次]
```

## 日志配置

日志统一通过 `src/utils/logger.py` 输出（colorlog）：

```bash
LOG_LEVEL=DEBUG uv run python src/simple/complete_example.py   # 调试模式
LOG_LEVEL=INFO  uv run python src/simple/complete_example.py   # 正常模式
LOG_LEVEL=WARNING uv run python src/simple/complete_example.py # 生产模式
```

格式示例：
```
INFO     [complete_example.py:50]  main  [complete] 创建沙箱 image=opensandbox/code-interpreter:v1.0.2
INFO     [complete_example.py:60]  main  [sandbox] id=ac53adfb-e2e5-4058-845d-7250db4fdb36
```

## 环境变量说明

| 变量 | 说明 | 示例 |
|------|------|------|
| `SANDBOX_DOMAIN` | 沙箱服务地址 | `localhost:8080` |
| `SANDBOX_IMAGE` | 沙箱镜像 | `opensandbox/code-interpreter:v1.0.2` |
| `LLM_BACKEND` | LLM 后端选择 | `moonshot` / `vllm` / `oneapi` / `minimax` |
| `OPENAI_API_KEY` | OpenAI/MiniMax API Key | `sk-cp-...` |

> **注意**: 所有密钥必须写在 `.env` 中，禁止硬编码到代码里。

## 核心 API 概览

```python
from opensandbox import Sandbox
from opensandbox.config import ConnectionConfig
from opensandbox.models.execd import ExecutionHandlers
from datetime import timedelta

config = ConnectionConfig(domain="localhost:8080")

sandbox = await Sandbox.create(
    "opensandbox/code-interpreter:v1.0.2",
    entrypoint=["/opt/opensandbox/code-interpreter.sh"],
    timeout=timedelta(minutes=5),
    connection_config=config,
)

async with sandbox:
    # 写文件
    await sandbox.files.write_file("/workspace/script.py", "print('hello')")

    # 流式执行
    handlers = ExecutionHandlers(
        on_stdout=lambda msg: print(f"Output: {msg.text}"),
    )
    result = await sandbox.commands.run("python3 /workspace/script.py", handlers=handlers)

    # 获取指标
    metrics = await sandbox.get_metrics()
    print(f"Memory: {metrics.memory_used_in_mib} MB")

    # 清理
    await sandbox.kill()
```

## 参考文档

- [OpenSandbox 官方文档](https://opensandbox.io)
- `docs/litellm-proxy-guide.md` — LiteLLM Proxy 配置指南
- `docs/sandbox-pool-guide.md` — 沙箱池配置指南