示例

本节提供使用 AIO Sandbox 在实际场景中的实用示例和集成指南。

快速示例

终端集成

了解如何将 WebSocket 终端集成到您的应用程序中:

浏览器自动化

探索浏览器自动化功能:

Agent 集成

使用 AIO Sandbox 构建 AI Agent:

集成模式

Docker Compose 设置

version: '3.8'
services:
  aio-sandbox:
    image: ghcr.io/agent-infra/sandbox:v1
    ports:
      - "8080:8080"
    volumes:
      - sandbox_data:/workspace
    restart: unless-stopped

volumes:
  sandbox_data:

Kubernetes 部署

apiVersion: apps/v1
kind: Deployment
metadata:
  name: aio-sandbox
spec:
  replicas: 2
  selector:
    matchLabels:
      app: aio-sandbox
  template:
    metadata:
      labels:
        app: aio-sandbox
    spec:
      containers:
      - name: sandbox
        image: ghcr.io/agent-infra/sandbox:v1
        ports:
        - containerPort: 8080
        resources:
          requests:
            memory: "1Gi"
            cpu: "500m"
          limits:
            memory: "2Gi"
            cpu: "1000m"
---
apiVersion: v1
kind: Service
metadata:
  name: aio-sandbox-service
spec:
  selector:
    app: aio-sandbox
  ports:
  - port: 80
    targetPort: 8080
  type: LoadBalancer

SDK 示例

Python SDK

安装 AIO Sandbox 的 Python SDK:

pip install aio-sandbox

基本配置

导入并配置 Python 客户端:

from aio_sandbox import AioClient
import asyncio

# 初始化客户端
client = AioClient(
    base_url="http://localhost:8080",  # AIO Sandbox URL
    timeout=30.0,  # 请求超时(秒)
    retries=3,     # 重试次数
    retry_delay=1.0  # 重试之间的延迟
)

Shell 操作

执行 Shell 命令并管理会话:

async def shell_example():
    # 执行简单命令
    result = await client.shell.exec(command="ls -la")

    if result.success:
        print(f"输出:{result.data.output}")
        print(f"退出码:{result.data.exit_code}")

    # 使用会话管理执行
    session_id = "my-session-1"
    await client.shell.exec(
        command="cd /workspace && pwd",
        session_id=session_id
    )

    # 在同一会话中继续
    result = await client.shell.exec(
        command="ls",
        session_id=session_id
    )

    # 长时间运行任务的异步执行
    await client.shell.exec(
        command="python long_script.py",
        async_mode=True,
        session_id=session_id
    )

    # 查看会话输出
    view_result = await client.shell.view(session_id=session_id)
    print(view_result.data.output)

# 运行示例
asyncio.run(shell_example())

文件操作

管理文件和目录:

async def file_example():
    # 写入文件
    await client.file.write(
        file="/tmp/example.py",
        content="""
import matplotlib.pyplot as plt
import numpy as np

x = np.linspace(0, 10, 100)
y = np.sin(x)

plt.plot(x, y)
plt.savefig('/tmp/plot.png')
print("图表已保存!")
        """.strip()
    )

    # 读取文件内容
    content = await client.file.read(file="/tmp/example.py")
    if content.success:
        print(f"文件内容:\n{content.data.content}")

    # 列出目录内容
    files = await client.file.list(
        path="/tmp",
        recursive=True,
        include_size=True
    )

    for file_info in files.data.files:
        print(f"{file_info.name}: {file_info.size} 字节")

    # 在文件中搜索
    search_result = await client.file.search(
        file="/tmp/example.py",
        regex=r"import \w+"
    )

    if search_result.success:
        for match in search_result.data.matches:
            print(f"第 {match.line} 行:{match.content}")

    # 按模式查找文件
    found_files = await client.file.find(
        path="/tmp",
        glob="*.py"
    )

asyncio.run(file_example())

代码执行

安全地执行 Python 和 JavaScript 代码:

async def code_execution_example():
    # 在 Jupyter 内核中执行 Python 代码
    jupyter_result = await client.jupyter.execute(
        code="""
import pandas as pd
import numpy as np

# 创建示例数据
df = pd.DataFrame({
    'x': np.random.randn(100),
    'y': np.random.randn(100)
})

print(f"DataFrame 形状:{df.shape}")
print(df.head())
        """,
        timeout=60,
        session_id="data-analysis-session"
    )

    if jupyter_result.success:
        print("Jupyter 输出:")
        for output in jupyter_result.data.outputs:
            if output.output_type == "stream":
                print(output.text)
            elif output.output_type == "execute_result":
                print(output.data.get("text/plain", ""))

    # 执行 Node.js 代码
    nodejs_result = await client.nodejs.execute(
        code="""
const fs = require('fs');
const path = require('path');

// 如果存在则读取 package.json
try {
    const packagePath = path.join(process.cwd(), 'package.json');
    if (fs.existsSync(packagePath)) {
        const pkg = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
        console.log(`项目:${pkg.name || '未知'}`);
        console.log(`版本:${pkg.version || '未知'}`);
    } else {
        console.log('未找到 package.json');
    }
} catch (error) {
    console.error('错误:', error.message);
}
        """,
        timeout=30
    )

    if nodejs_result.success:
        print(f"Node.js 输出:{nodejs_result.data.stdout}")

asyncio.run(code_execution_example())

MCP 集成

使用模型上下文协议服务:

async def mcp_example():
    # 列出可用的 MCP 服务器
    servers = await client.mcp.list_servers()
    print("可用的 MCP 服务器:", servers.data)

    # 从特定服务器获取工具
    browser_tools = await client.mcp.list_tools(server_name="browser")

    for tool in browser_tools.data.tools:
        print(f"工具:{tool.name}")
        print(f"描述:{tool.description}")

    # 执行工具
    screenshot_result = await client.mcp.execute_tool(
        server_name="browser",
        tool_name="screenshot",
        arguments={
            "url": "https://example.com",
            "width": 1920,
            "height": 1080
        }
    )

    if screenshot_result.success:
        # 保存截图数据
        await client.file.write(
            file="/tmp/screenshot.png",
            content=screenshot_result.data.content[0].data,  # Base64 图像数据
            append=False
        )

asyncio.run(mcp_example())

错误处理和最佳实践

async def robust_example():
    try:
        # 始终使用上下文管理器进行资源清理
        async with AioClient("http://localhost:8080") as client:
            # 设置错误处理
            result = await client.shell.exec("potentially-failing-command")

            if not result.success:
                print(f"命令失败:{result.message}")
                if hasattr(result, 'error_code'):
                    print(f"错误代码:{result.error_code}")

            # 检查沙盒状态
            status = await client.sandbox.get_context()
            print(f"沙盒运行时间:{status.data.uptime}")
            print(f"可用包:{len(status.data.packages)}")

    except Exception as e:
        print(f"连接错误:{e}")

asyncio.run(robust_example())

Node.js SDK

要安装 SDK,请使用以下命令:

npm install @agent-infra/sandbox

基本配置

首先导入 SDK 并配置客户端:

import { AioClient } from "@agent-infra/sandbox";

const client = new AioClient({
  baseUrl: `https://{aio.sandbox.example}`, // URL 和端口应与 Aio Sandbox 一致
  timeout: 30000, // 可选:请求超时(毫秒)
  retries: 3, // 可选:重试次数
  retryDelay: 1000, // 可选:重试之间的延迟(毫秒)
});

Shell 执行

在沙盒内执行 Shell 命令:

const response = await client.shellExec({
  command: "ls -la",
});

if (response.success) {
  console.log("命令输出:", response.data.output);
} else {
  console.error("错误:", response.message);
}

// 异步轮询训练结果,适用于长期任务
const response = await client.shellExecWithPolling({
  command: "ls -la",
  maxWaitTime: 60 * 1000,
});

文件管理

列出目录中的文件:

const fileList = await client.fileList({
  path: "/home/gem",
  recursive: true,
});

if (fileList.success) {
  console.log("文件:", fileList.data.files);
} else {
  console.error("错误:", fileList.message);
}

Jupyter 代码执行

运行 Jupyter notebook 代码:

const jupyterResponse = await client.jupyterExecute({
  code: "print('你好,Jupyter!')",
  kernel_name: "python3",
});

if (jupyterResponse.success) {
  console.log("输出:", jupyterResponse.data);
} else {
  console.error("错误:", jupyterResponse.message);
}

下一步

准备好实施这些模式了吗?选择您的路径:

如需其他支持: