AgentRun 实践指南：Agent 的宝藏工具——All-In-One Sandbox

▍为什么选择 AIO？

架构一览

统一文件系统

我们的解决方案很简单粗暴：把所有组件（浏览器、Shell、代码执行、文件系统）都塞进同一个沙箱实例里。

性能对比一目了然：

▍1.1 核心概念

▍1.2 快速开始

pip install agentrun-sdk['server','playwright']

from agentrun.sandbox import Sandbox, TemplateTypeimport asyncioasync def quick_start():    """验证沙箱基本功能"""    sandbox = Sandbox.create(        template_type=TemplateType.AIO,        template_name="quick-test",        sandbox_idle_timeout_seconds=600    )    print(f"沙箱已创建: {sandbox.sandbox_id}")    # 核心：连接已运行的浏览器，提取页面信息    code = """const puppeteer = require('puppeteer-core');const browser = await puppeteer.connect({  browserWSEndpoint: 'ws://localhost:5000/ws/automation'});const page = (await browser.pages())[0];await page.goto('https://example.com');console.log(await page.title());await browser.disconnect();"""    await sandbox.context.execute_async(code=code, language="javascript")    sandbox.destroy()asyncio.run(quick_start())

const puppeteer = require('puppeteer-core');const browser = await puppeteer.connect({  browserWSEndpoint: 'ws://localhost:5000/ws/automation'});const page = (await browser.pages())[0];await page.goto('https://example.com/login');console.log('请在 VNC 中完成登录');await browser.disconnect();

const fs = require('fs');const puppeteer = require('puppeteer-core');const browser = await puppeteer.connect({  browserWSEndpoint: 'ws://localhost:5000/ws/automation'});const page = (await browser.pages())[0];const cookies = await page.cookies();fs.writeFileSync('/home/user/data/cookies.json', JSON.stringify(cookies));console.log('Cookie 已保存');await browser.disconnect();

const fs = require('fs');const puppeteer = require('puppeteer-core');const browser = await puppeteer.connect({  browserWSEndpoint: 'ws://localhost:5000/ws/automation'});const page = (await browser.pages())[0];const cookies = JSON.parse(fs.readFileSync('/home/user/data/cookies.json'));await page.setCookie(...cookies);await page.goto('https://example.com/data');// 执行数据采集await browser.disconnect();

▍1.3 关键概念说明

result = await sandbox.context.execute_async(    code="console.log('Hello')",    language="javascript",  # 或 "python"    timeout=300  # 超时时间（秒）)

{    "contextId": "ctx_xxx",  # 上下文 ID    "results": [        {"type": "stdout", "text": "Hello\n"},        {"type": "result", "value": null}    ]}

# 写入文件sandbox.file.write(    path="/home/user/data/result.json",    content='{"key": "value"}',    encoding="utf-8")# 读取文件content = sandbox.file.read("/home/user/data/result.json")# 上传本地文件sandbox.file_system.upload(    local_file_path="./local_file.txt",    target_file_path="/home/user/data/file.txt")# 下载文件sandbox.file_system.download(    path="/home/user/data/result.json",    save_path="./result.json")

▍2.1 多步骤任务模式

步骤 1：打开登录页 → 通过 VNC 人工登录步骤 2：保存 Cookie 到文件系统步骤 3：使用 Cookie 执行数据采集

▍2.2 LLM Agent 集成模式

▍2.3 Cookie 持久化模式

首次登录：1. 人工登录 → 2. 保存 Cookie → 3. 持久化存储后续使用：1. 上传Cookie -> 2. 读取 Cookie → 3. 恢复会话 → 4. 执行任务

const puppeteer = require('puppeteer-core');const fs = require('fs');const browser = await puppeteer.connect({  browserWSEndpoint: 'ws://localhost:5000/ws/automation'});const page = (await browser.pages())[0];const cookies = await page.cookies();// 保存到文件系统fs.writeFileSync('/home/user/data/cookies.json', JSON.stringify(cookies, null, 2));console.log('Cookie 已保存');await browser.disconnect();

const puppeteer = require('puppeteer-core');const fs = require('fs');const browser = await puppeteer.connect({  browserWSEndpoint: 'ws://localhost:5000/ws/automation'});const page = (await browser.pages())[0];// 读取 Cookieconst cookies = JSON.parse(fs.readFileSync('/home/user/data/cookies.json'));// 恢复会话await page.setCookie(...cookies);await page.goto('https://example.com/protected');console.log('登录状态已恢复');await browser.disconnect();

▍2.4 批量任务模式

策略 1：单沙箱顺序执行（简单任务，有依赖关系）策略 2：多沙箱并发执行（复杂任务，无依赖关系）

# 使用 asyncio.gather() 实现并发tasks = [    process_item(item)    for item in items]results = await asyncio.gather(*tasks, return_exceptions=True)

▍3.1 需求分析

▍3.2 核心实现流程

// 1. 打开登录页const puppeteer = require('puppeteer-core');const browser = await puppeteer.connect({  browserWSEndpoint: 'ws://localhost:5000/ws/automation'});const page = (await browser.pages())[0];await page.goto('https://accounts.douban.com/passport/login');console.log('请在 VNC 中完成登录');console.log('登录完成后，程序将自动保存 Cookie');await browser.disconnect();

const puppeteer = require('puppeteer-core');const fs = require('fs');const browser = await puppeteer.connect({  browserWSEndpoint: 'ws://localhost:5000/ws/automation'});const page = (await browser.pages())[0];const cookies = await page.cookies();fs.writeFileSync('/home/user/data/douban_cookies.json', JSON.stringify(cookies, null, 2));console.log(`Cookie 已保存，共 ${cookies.length} 条`);await browser.disconnect();

const puppeteer = require('puppeteer-core');const fs = require('fs');const browser = await puppeteer.connect({  browserWSEndpoint: 'ws://localhost:5000/ws/automation'});const page = (await browser.pages())[0];// 恢复 Cookieconst cookies = JSON.parse(fs.readFileSync('/home/user/data/douban_cookies.json'));await page.setCookie(...cookies);// 访问 Top250await page.goto('https://movie.douban.com/top250', { waitUntil: 'networkidle2' });// 提取数据const movies = await page.evaluate(() => {  return Array.from(document.querySelectorAll('.item')).map(item => ({    title: item.querySelector('.title')?.textContent,    rating: item.querySelector('.rating_num')?.textContent,    quote: item.querySelector('.inq')?.textContent  }));});// 保存结果fs.writeFileSync('/home/user/data/movies.json', JSON.stringify(movies, null, 2));console.log(`爬取完成，共 ${movies.length} 部电影`);await browser.disconnect();

▍3.3 完整 Python 代码

from agentrun.sandbox import Sandbox, TemplateTypeimport asyncioasync def scrape_douban():    # 1. 创建沙箱    sandbox = Sandbox.create(        template_type=TemplateType.AIO,        template_name="douban-scraper",        sandbox_idle_timeout_seconds=1800    )    # 2. 执行登录步骤（代码略，参考上面）    # 3. 保存 Cookie（代码略，参考上面）    # 4. 爬取数据（代码略，参考上面）    # 5. 读取结果    result = sandbox.file.read('/home/user/data/movies.json')    print(result)asyncio.run(scrape_douban())

▍3.4 核心技术点总结

▍3.5 扩展功能

const movies = [];for (let page_num = 0; page_num < 250; page_num += 25) {  await page.goto(`https://movie.douban.com/top250?start=${page_num}`);  const items = await page.evaluate(() => {    // 提取逻辑  });  movies.push(...items);  // 延迟防止反爬  await page.waitForTimeout(2000);}fs.writeFileSync('/home/user/data/all_movies.json', JSON.stringify(movies));

async function scrapeWithRetry(url, maxRetries = 3) {  for (let i = 0; i < maxRetries; i++) {    try {      await page.goto(url, { waitUntil: 'networkidle2', timeout: 30000 });      return true;    } catch (error) {      console.log(`重试 ${i + 1}/${maxRetries}: ${error.message}`);      await page.waitForTimeout(5000);    }  }  return false;}

▍4.1 为什么提示词这么重要？

▍4.2 我们的设计哲学

▍4.3 核心约束与最佳实践

传统方式 (错误):const browser = await puppeteer.launch();  // 启动新浏览器 (1-3 秒)// 执行任务await browser.close();  // 状态全部丢失All-In-One 方式 (正确):const browser = await puppeteer.connect({  // 连接已运行的浏览器 (<100ms)  browserWSEndpoint: 'ws://localhost:5000/ws/automation'});// 执行任务await browser.disconnect();  // 保持浏览器运行

browser.close():- 关闭所有页面- 终止浏览器进程- 清理所有状态- 无法支持多步骤任务- VNC 显示中断browser.disconnect():- 只断开 Puppeteer 连接- 浏览器继续运行- 所有状态保留- 支持多步骤任务- VNC 显示连续

用户登录 → 服务器设置 Cookie → 后续请求携带 Cookie → 服务器识别用户

const cookies = await page.cookies();fs.writeFileSync(  '/home/user/data/cookies.json',  JSON.stringify(cookies, null, 2));

const cookies = JSON.parse(  fs.readFileSync('/home/user/data/cookies.json'));// 先访问对应域名await page.goto('https://example.com');// 再设置 Cookieawait page.setCookie(...cookies);

▍4.4 实用提示词模板

你是 AgentRun AIO Sandbox 的代码生成助手。你的任务是将用户需求转换为可在沙箱中执行的 Puppeteer 代码。【环境信息】- 浏览器：Chromium (已预启动)- 连接端点：ws://localhost:5000/ws/automation- 文件系统：/home/user/data/ (持久化目录)- 超时限制：单次执行 300 秒【代码规范】1. 连接浏览器：   const puppeteer = require('puppeteer-core');   const browser = await puppeteer.connect({     browserWSEndpoint: 'ws://localhost:5000/ws/automation'   });2. 结束会话：   await browser.disconnect();3. 文件读写：   const fs = require('fs');   // 读取   const data = fs.readFileSync('/home/user/data/file.json');   // 写入   fs.writeFileSync('/home/user/data/file.json', JSON.stringify(data));4. 错误处理：   try {     // 代码逻辑   } catch (error) {     console.error(`错误: ${error.message}`);     throw error;   }【输出要求】- 生成完整的 JavaScript 代码- 包含必要的错误处理- 关键步骤用 console.log() 记录- 重要结果保存到文件系统

▍4.5 AI 对话模式的工作原理

用户: 访问 example.com，获取页面标题AI 直接生成单个代码块，执行后返回结果

用户: 登录豆瓣，然后获取我的收藏AI 自动拆分为 3 个步骤：步骤 1: 打开登录页 → [生成代码1] → "请在 VNC 中完成登录"步骤 2: 保存 Cookie → [生成代码2] → "已保存 15 个 Cookie"步骤 3: 获取收藏 → [生成代码3] → "找到 25 部收藏电影"

AI: 我已经打开了登录页面，请在 VNC 窗口中：1. 输入用户名和密码2. 输入验证码3. 点击登录按钮完成后告诉我"登录完成"，我将继续后续步骤。

▍5.1 错误处理（生产环境必备）

try {  // 核心操作  await page.goto(url, { waitUntil: 'networkidle2', timeout: 30000 });} catch (error) {  // 明确的错误信息  console.error(`操作失败: ${error.message}`);  // 可选：重试逻辑  if (error.name === 'TimeoutError' && retryCount < maxRetries) {    console.log(`超时，重试第 ${retryCount + 1} 次`);    await new Promise(resolve => setTimeout(resolve, 5000));    return executeWithRetry(url, retryCount + 1);  }  throw error;}

▍5.2 性能优化（速度提升明显）

await page.setRequestInterception(true);page.on('request', (req) => {  const resourceType = req.resourceType();  // 丢弃图片、样式、字体等非关键资源  if (['image', 'stylesheet', 'font', 'media'].includes(resourceType)) {    req.abort();  } else {    req.continue();  }});

# .gitignore 中必须包含*_cookies.jsoncookies.json*.env

// 危险：直接拼接用户输入const userInput = req.query.selector;await page.click(userInput);// 安全：白名单验证const allowedSelectors = ['.button-primary', '.submit-btn'];if (!allowedSelectors.includes(userInput)) {  throw new Error('非法选择器');}await page.click(userInput);

▍5.4 调试技巧（省时省力）

# 创建沙箱后立即获取 VNC URLvnc_url = f"https://vnc.example.com/sandbox/{sandbox.sandbox_id}"print(f"打开 VNC: {vnc_url}")

// 登录前后都截图await page.screenshot({ path: '/home/user/data/before_login.png', fullPage: true });await page.screenshot({ path: '/home/user/data/after_login.png', fullPage: true });

▍技术收益一目了然

▍7 条黄金法则

▍常见陷阱避坑指南