Harness 与 Agent 工程 · 运行控制与长任务 · 2026-02-24

进阶指南:BrowserUse + AgentRun Sandbox 最佳实践

掌握BrowserUse与AgentRun Sandbox的高级集成方案,解锁生产环境部署的完整实践指南。

核心内容:

  1. BrowserUse框架与Browser Sandbox的深度集成架构解析
  2. 生产环境部署的关键考量:性能优化、安全性与可观测性
  3. 实战演示:从环境配置到智能决策循环的完整工作流

前言

Cloud Native

在完成了 Browser Sandbox 的基础集成之后,本文将介绍高级集成方案(如 BrowserUse 框架)以及生产环境部署需要考虑的因素:如何管理 Sandbox 生命周期?如何优化性能和成本?如何保证系统的安全性和可观测性?本文将为您提供全面的高级应用和生产环境最佳实践指南。

基于 BrowserUse 集成 Browser Sandbox

Cloud Native

效果截图

BrowserUse 是一个专门为 AI Agent 设计的浏览器自动化框架,支持视觉理解和智能决策。通过 AgentRun Browser Sandbox,您可以让 BrowserUse 在云端运行,享受 Serverless 架构的优势。

BrowserUse 架构概览下图展示了 BrowserUse 与 Browser Sandbox 的集成架构:

架构特点:

  1. 智能决策循环:Agent 通过 LLM 分析页面截图,基于视觉理解生成操作指令,执行操作后继续循环,直到任务完成
  2. 无头浏览器控制:通过 CDP 协议远程控制云端浏览器,Playwright 作为底层驱动,所有操作在云端执行
  3. 实时可视化:VNC 提供实时画面监控,方便调试和验证 Agent 行为

快速开始

安装依赖

pip install browser-use python-dotenv agentrun-sdk[playwright,server]

主要依赖说明:

配置环境变量

创建 .env 文件:

## DashScope API Key(用于 Qwen 模型)DASHSCOPE_API_KEY=sk-your-dashscope-api-key# AgentRun 认证信息AGENTRUN_ACCOUNT_ID=your-account-idALIBABA_CLOUD_ACCESS_KEY_ID=your-access-key-idALIBABA_CLOUD_ACCESS_KEY_SECRET=your-access-key-secret# Browser Sandbox 模板名称BROWSER_TEMPLATE_NAME=sandbox-browser-demo

创建 Sandbox 并使用 BrowserUse

import asyncioimport osfrom agentrun.sandbox import Sandbox, TemplateTypefrom browser_use import Agent, BrowserSession, ChatOpenAIfrom browser_use.browser import BrowserProfilefrom dotenv import load_dotenvload_dotenv()async def main(): # 创建 Browser Sandbox sandbox = Sandbox.create( template_type=TemplateType.BROWSER, template_name=os.getenv("BROWSER_TEMPLATE_NAME"), sandbox_idle_timeout_seconds=3000 ) # 配置 Qwen 多模态模型 llm = ChatOpenAI( model='qwen-vl-max', api_key=os.getenv("DASHSCOPE_API_KEY"), base_url="https://dashscope.aliyuncs.com/compatible-mode/v1" ) # 创建浏览器会话 browser_session = BrowserSession( cdp_url=sandbox.get_cdp_url(), browser_profile=BrowserProfile( headless=False, timeout=3000000, keep_alive=True ) ) # 创建 Agent 并执行任务 agent = Agent( task="访问阿里云官网并总结主要产品分类", llm=llm, browser_session=browser_session, use_vision=True ) result = await agent.run() print(f"任务结果: {result.final_result()}") # 清理资源 await browser_session.stop() sandbox.delete()if __name__ == "__main__": asyncio.run(main())

BrowserUse 高级配置

自定义浏览器行为

browser_profile = BrowserProfile( timeout=3000000, # 超时时间(毫秒) keep_alive=True, # 保持会话活跃)

多步骤任务编排

async def complex_task(): """复杂的多步骤任务""" sandbox = Sandbox.create( template_type=TemplateType.BROWSER, template_name=os.getenv("BROWSER_TEMPLATE_NAME"), sandbox_idle_timeout_seconds=3000 ) llm = ChatOpenAI( model='qwen-vl-max', api_key=os.getenv("DASHSCOPE_API_KEY"), base_url="https://dashscope.aliyuncs.com/compatible-mode/v1" ) browser_session = BrowserSession( cdp_url=sandbox.cdp_url, browser_profile=BrowserProfile(keep_alive=True) ) # 任务 1:信息收集 agent1 = Agent( task="访问阿里云官网,收集产品分类信息", llm=llm, browser_session=browser_session, use_vision=True ) result1 = await agent1.run() # 任务 2:基于第一步结果继续操作 agent2 = Agent( task=f"基于以下信息:{result1.final_result()},访问每个产品分类并提取关键特性", llm=llm, browser_session=browser_session, use_vision=True ) result2 = await agent2.run() # 清理资源 await browser_session.stop() sandbox.delete() return result2.final_result()

集成 VNC 实时监控

import webbrowserimport urllib.parseasync def run_with_vnc_monitoring(): """运行 BrowserUse 并启用 VNC 监控""" sandbox = Sandbox.create( template_type=TemplateType.BROWSER, template_name=os.getenv("BROWSER_TEMPLATE_NAME"), sandbox_idle_timeout_seconds=3000 ) # 获取 VNC URL 并打开查看器 vnc_url = sandbox.get_vnc_url(), if vnc_url: # 修复 VNC URL 路径 if vnc_url.endswith('/vnc'): vnc_url = vnc_url[:-4] + '/ws/livestream' # 在浏览器中打开 VNC 查看器 encoded_url = urllib.parse.quote(vnc_url, safe='') viewer_url = f"file://path/to/vnc-viewer.html?url={encoded_url}" webbrowser.open(viewer_url) print(f"VNC 查看器已打开,可实时监控浏览器操作") # 创建并运行 Agent llm = ChatOpenAI( model='qwen-vl-max', api_key=os.getenv("DASHSCOPE_API_KEY"), base_url="https://dashscope.aliyuncs.com/compatible-mode/v1" ) browser_session = BrowserSession( cdp_url=sandbox.get_cdp_url(), browser_profile=BrowserProfile(headless=False, keep_alive=True) ) agent = Agent( task="访问淘宝首页并搜索商品", llm=llm, browser_session=browser_session, use_vision=True ) result = await agent.run() # 清理资源 await browser_session.stop() sandbox.delete() return result.final_result()

BrowserUse 最佳实践

  1. 启用视觉理解:对于复杂页面,使用use_vision=True 让 LLM 分析页面截图
  2. 保持会话活跃:使用keep_alive=True 避免频繁重建连接
  3. 合理设置超时:根据任务复杂度调整timeout 参数
  4. 复用 BrowserSession:对于多步骤任务,复用同一个 BrowserSession 提高效率
  5. 结合 VNC 调试:开发阶段启用 VNC 实时查看 Agent 行为

获取完整示例代码本文中的所有示例代码都可以在以下仓库中找到:

## 克隆示例代码仓库git clone https://github.com/devsapp/agentrun-sandbox-demos.git# 进入项目目录cd agentrun-browseruse-wth-sandbox-demo# 安装依赖(注意需要安装 server 扩展)pip install -r requirements.txt

配置环境变量

## 复制环境变量模板cp env.example .env# 编辑 .env 文件,填入您的配置信息# 必需配置项:# - DASHSCOPE_API_KEY: DashScope API Key(用于 Qwen 模型)# - AGENTRUN_ACCOUNT_ID: AgentRun 账号 ID# - ALIBABA_CLOUD_ACCESS_KEY_ID: 阿里云访问密钥 ID# - ALIBABA_CLOUD_ACCESS_KEY_SECRET: 阿里云访问密钥 Secret# - BROWSER_TEMPLATE_NAME: Browser Sandbox 模板名称

运行示例(两步运行设计)

本项目采用服务器-客户端的架构设计,需要分两步运行:

第一步:启动 VNC 查看器服务

## 在终端 1 中启动 VNC Web 服务器python main.py# 服务启动后会显示:# VNC 查看器服务已启动: http://localhost:8000# 访问 http://localhost:8000 可以实时查看浏览器操作

main.py 的作用:

第二步:运行 BrowserUse 示例

## 在终端 2 中运行示例代码python examples/01_browseruse_basic.py# 运行高级示例python examples/02_browseruse_advanced.py

为什么需要两步运行?

  1. 实时监控:main.py 提供 VNC 查看器,可以实时看到 Agent 在浏览器中的操作
  2. 调试友好:通过可视化界面,更容易理解 Agent 的决策过程和行为
  3. 服务解耦:VNC 服务和业务逻辑分离,可以同时运行多个示例而共用同一个查看器

运行流程图:

仓库内容包括:

Sandbox 生命周期管理最佳实践

Cloud Native

三种管理模式根据不同的应用场景,我们推荐三种 Sandbox 管理模式:

方案对比:

单例模式实现适合开发调试和多轮对话场景:

class SandboxManager: """单例模式 Sandbox 管理器""" _instance = None _sandbox = None def __new__(cls): if cls._instance is None: cls._instance = super().__new__(cls) return cls._instance def get_or_create(self): """获取或创建 Sandbox""" if self._sandbox is None: self._sandbox = Sandbox.create( template_type=TemplateType.BROWSER, template_name=os.getenv("BROWSER_TEMPLATE_NAME"), sandbox_idle_timeout_seconds=3000 ) return self._sandbox def destroy(self): """销毁 Sandbox""" if self._sandbox: self._sandbox.delete() self._sandbox = None# 使用manager = SandboxManager()sandbox = manager.get_or_create() # 首次创建sandbox = manager.get_or_create() # 复用现有实例

连接池模式实现适合高并发生产环境:

from queue import Queuefrom threading import Lockclass SandboxPool: """Sandbox 连接池""" def __init__(self, pool_size=5, max_idle_time=300): self.pool_size = pool_size self.max_idle_time = max_idle_time self.pool = Queue(maxsize=pool_size) self.lock = Lock() self._initialize_pool() def _initialize_pool(self): """初始化连接池""" for _ in range(self.pool_size): sandbox = self._create_sandbox() self.pool.put(sandbox) def _create_sandbox(self): """创建 Sandbox 实例""" return Sandbox.create( template_type=TemplateType.BROWSER, template_name=os.getenv("BROWSER_TEMPLATE_NAME"), sandbox_idle_timeout_seconds=self.max_idle_time ) def acquire(self, timeout=30): """获取 Sandbox 实例""" try: sandbox = self.pool.get(timeout=timeout) if not self._is_alive(sandbox): sandbox = self._create_sandbox() return sandbox except: raise RuntimeError("获取 Sandbox 超时") def release(self, sandbox): """归还 Sandbox 实例""" if self._is_alive(sandbox): self.pool.put(sandbox) else: new_sandbox = self._create_sandbox() self.pool.put(new_sandbox) def _is_alive(self, sandbox): """检查 Sandbox 是否存活""" try: return hasattr(sandbox, 'sandbox_id') except: return False# 使用pool = SandboxPool(pool_size=5)sandbox = pool.acquire()try: # 使用 sandbox 执行任务 passfinally: pool.release(sandbox)

会话状态管理支持多用户多会话场景:

import timeclass SessionManager: """会话状态管理""" def __init__(self): self.sessions = {} # session_id -> sandbox def create_session(self…
— 以上为试看内容(约 40%),开通会员后阅读全文 —

原文出处:https://www.53ai.com/news/langchain/2026022420145.html