快速上手：LangChain + AgentRun 浏览器沙箱极简集成指南

前言

在 Agentic AI 时代,智能体需要与真实世界交互,而浏览器是连接虚拟世界与现实世界的重要桥梁。AgentRun Browser Sandbox 为智能体提供了安全、高性能、免运维的浏览器执行环境,让 AI Agent 真正具备"上网"的能力——从网页抓取、信息提取到表单填写、自动化操作,一切皆可实现。
AgentRun Browser Sandbox 介绍

什么是 Browser Sandbox?

Browser Sandbox 是 AgentRun 平台提供的云原生无头浏览器沙箱服务,基于阿里云函数计算（FC）构建。它为智能体提供了一个安全隔离的浏览器执行环境,支持通过标准的 Chrome DevTools Protocol (CDP) 远程控制浏览器实例。
核心特性

无头浏览器能力

• 内置 Chromium/Chrome 浏览器,支持完整的 Web 标准
  
• 原生兼容 Puppeteer、Playwright 等主流自动化框架
  
• 支持通过 CDP 协议进行精细化控制
  

实时可视化

• 内置 VNC 服务,支持实时查看浏览器界面
  
• 提供操作录制功能,方便调试和回放
  
• 支持通过 noVNC 客户端在网页中直接观看
  

安全与隔离

• 每个沙箱实例运行在独立的容器环境中
  
• 文件系统和进程空间完全隔离
  
• 支持 WSS 加密传输,确保数据安全
  

Serverless 架构

• 按需创建,按量付费,无需提前预置资源
  
• 快速弹性伸缩,支持高并发场景
  
• 零运维,无需管理服务器和浏览器依赖
  

主要应用场景

• AI Agent 赋能: 为大模型提供"眼睛"和"手",执行网页浏览、信息提取、在线操作等任务
  
• 自动化测试: 在云端运行端到端（E2E）测试和视觉回归测试
  
• 数据采集: 稳定、高效地进行网页抓取,应对动态加载和反爬虫挑战
  
• 内容生成: 自动化生成网页截图或 PDF 文档
  

上手使用 Agentrun Browser Sandbox

AgentRun SDK 快速介绍

后续的内容将基于 Agentrun SDK 进行，因此我们先对 SDK 进行简要介绍

AgentRun SDK 是一个开源的 Python 工具包,旨在简化智能体与 AgentRun 平台各种服务（包括 Browser Sandbox）的集成。它提供了统一的接口,让您可以用几行代码就将沙箱能力集成到现有的 Agent 框架中。SDK 的核心功能如下：
统一集成接口

• 提供对 LangChain、AgentScope 等主流框架的开箱即用支持
  
• 统一的模型代理接口,简化多模型管理
  
• 标准化的工具注册机制
  

Sandbox 生命周期管理

• 自动创建和销毁沙箱实例
  
• 支持会话级别的状态保持
  
• 灵活的资源配置和超时控制
  

安装 AgentRun SDK

1. pip install agentrun-sdk[playwright,server]

复制代码

注意: 确保您的 Python 环境版本在 3.10 及以上。

基本使用示例

以下是使用 AgentRun SDK 创建和管理 Browser Sandbox 的核心代码：

1. from agentrun.sandbox import Sandbox, TemplateType
2. from playwright.sync_api import sync_playwright
4. # 创建 Browser Sandbox
5. sandbox = Sandbox.create(
6.     template_type=TemplateType.BROWSER,
7.     template_name="your-template-name",
8.     sandbox_idle_timeout_seconds=300
9. )
11. # 获取 CDP URL（用于 Playwright 连接）
12. cdp_url = sandbox.get_cdp_url()
14. # 使用 Playwright 连接并操作
15. with sync_playwright() as p:
16.     browser = p.chromium.connect_over_cdp(cdp_url)
17.     page = browser.contexts[0].pages[0]
18.    
19.     page.goto("https://www.example.com")
20.     page.screenshot(path="screenshot.png")
21.    
22.     browser.close()
24. # 销毁 Sandbox
25. sandbox.delete()

复制代码

关键概念：

• template_name: 控制台创建的浏览器环境模板
  
• cdp_url: 用于 Playwright/Puppeteer 连接
  
• vnc_url: 用于实时查看浏览器画面（可通过 sandbox.get_cdp_url() 获取）
  

注意: 由于所有浏览器操作都在云端进行，您无需在本地安装浏览器。Playwright 仅用于通过 CDP 协议连接到云端的浏览器实例。

如何创建 sandbox 模板

使用 Browser Sandbox 需要新建 Sandbox 模板，您需要访问  Agentrun 控制台网站，并按照如下步骤创建模板:

• 在顶部菜单栏选择“运行时与沙箱”；
  
• 在左侧边栏选择“Sandbox沙箱”；
  
• 点击右上角“创建沙箱模板”；
  

• 选择“浏览器”；
  
  
  
  
• 在弹出的抽屉对话框中填写和选择您的模板的规格、网络等配置，并复制模板名称；
  

6. 点击“创建浏览器” 等待其就绪即可。
从零开始用 LangChain 创建 Browser Sandbox 智能体

本教程将指导您从零开始创建一个完整的 Browser Sandbox 智能体项目。
基于 LangChain 集成 Browser Sandbox

本教程将详细讲解如何使用 LangChain 创建 Browser Sandbox 相关的 tools 并集成到 Agent 中。
项目结构

为了保持代码的内聚性和可维护性，我们将代码拆分为以下模块：
模块职责划分：

• sandbox_manager.py: 负责 Sandbox 的创建、管理和销毁，提供统一的接口
  
• langchain_agent.py: 负责创建 LangChain tools 和 Agent，集成 VNC 信息
  
• main.py: 作为入口文件，演示如何使用上述模块
  

步骤 1: 创建项目并安装依赖

首先创建项目目录（如果还没有）：

1. mkdir -p langchain-demo
2. cd langchain-demo

复制代码

创建 requirements.txt 文件，内容如下：

1. # LangChain 核心库
2. langchain>=0.1.0
3. langchain-openai>=0.0.5
4. langchain-community>=0.0.20
6. # AgentRun SDK
7. agentrun-sdk[playwright,server]>=0.0.8
9. # 浏览器自动化
10. playwright>=1.40.0
12. # 环境变量管理
13. python-dotenv>=1.0.0

复制代码

然后安装依赖：

1. pip install -r requirements.txt

复制代码

主要依赖说明：

• langchain 和 langchain-openai: LangChain 核心库
  
• agentrun-sdk[playwright,server]: AgentRun SDK，用于 Sandbox 管理
  
• playwright: 浏览器自动化库 python-dotenv: 环境变量管理
  

步骤 2: 配置环境变量

在项目根目录创建 .env 文件，配置以下环境变量：

1. # 阿里云百炼平台的 API Key，用于调用大模型能力
2. # 请前往 https://bailian.console.aliyun.com/?tab=app#/api-key 创建和查看
3. DASHSCOPE_API_KEY=sk-your-bailian-api-key
5. # 阿里云账号的访问密钥 ID 和访问密钥 Secret，用于 AgentRun SDK 鉴权
6. ALIBABA_CLOUD_ACCESS_KEY_ID=your-ak
7. ALIBABA_CLOUD_ACCESS_KEY_SECRET=your-sk
8. ALIBABA_CLOUD_ACCOUNT_ID=your-main-account-id
9. ALIBABA_CLOUD_REGION=cn-hangzhou
11. # browser sandbox 模板的名称，可以在 https://functionai.console.aliyun.com/cn-hangzhou/agent/runtime/sandbox 控制台创建
12. BROWSER_TEMPLATE_NAME=sandbox-your-template-name
14. # agentrun 的控制面和数据面的 API 端点请求地址，默认cn-hangzhou
15. AGENTRUN_CONTROL_ENDPOINT=agentrun.cn-hangzhou.aliyuncs.com
16. AGENTRUN_DATA_ENDPOINT=https://${your-main-account-id}.agentrun-data.cn-hangzhou.aliyuncs.com

复制代码

步骤 3: 创建 Sandbox 生命周期管理模块

创建 sandbox_manager.py 文件，负责 Sandbox 的创建、管理和销毁。核心代码如下：

1. """
2. Sandbox 生命周期管理模块
4. 负责 AgentRun Browser Sandbox 的创建、管理和销毁。
5. 提供统一的接口供 LangChain Agent 使用。
6. """
8. import os
9. from typing import Optional, Dict, Any
10. from dotenv import load_dotenv
12. # 加载环境变量
13. load_dotenv()
16. class SandboxManager:
17.     """Sandbox 生命周期管理器"""
18.    
19.     def __init__(self):
20.         self._sandbox: Optional[Any] = None
21.         self._sandbox_id: Optional[str] = None
22.         self._cdp_url: Optional[str] = None
23.         self._vnc_url: Optional[str] = None
24.    
25.     def create(
26.         self,
27.         template_name: Optional[str] = None,
28.         idle_timeout: int = 3000
29.     ) -> Dict[str, Any]:
30.         """
31.         创建或获取一个浏览器 sandbox 实例
32.         
33.         Args:
34.             template_name: Sandbox 模板名称，如果为 None 则从环境变量读取
35.             idle_timeout: 空闲超时时间（秒），默认 3000 秒
36.         
37.         Returns:
38.             dict: 包含 sandbox_id, cdp_url, vnc_url 的字典
39.         
40.         Raises:
41.             RuntimeError: 创建失败时抛出异常
42.         """
43.         try:
44.             from agentrun.sandbox import Sandbox, TemplateType
45.             
46.             # 如果已有 sandbox，直接返回
47.             if self._sandbox is not None:
48.                 return self.get_info()
49.             
50.             # 从环境变量获取模板名称
51.             if template_name is None:
52.                 template_name = os.getenv(
53.                     "BROWSER_TEMPLATE_NAME",
54.                     "sandbox-browser-demo"
55.                 )
56.             
57.             # 创建 sandbox
58.             self._sandbox = Sandbox.create(
59.                 template_type=TemplateType.BROWSER,
60.                 template_name=template_name,
61.                 sandbox_idle_timeout_seconds=idle_timeout
62.             )
63.             
64.             self._sandbox_id = self._sandbox.sandbox_id
65.             self._cdp_url = self._get_cdp_url()
66.             self._vnc_url = self._get_vnc_url()
67.             
68.             return self.get_info()
69.         
70.         except ImportError as e:
71.             print(e)
72.             raise RuntimeError(
73.                 "agentrun-sdk 未安装，请运行: pip install agentrun-sdk[playwright,server]"
74.             )
75.         except Exception as e:
76.             raise RuntimeError(f"创建 Sandbox 失败: {str(e)}")
77.    
78.     def get_info(self) -> Dict[str, Any]:
79.         """
80.         获取当前 sandbox 的信息
81.         
82.         Returns:
83.             dict: 包含 sandbox_id, cdp_url, vnc_url 的字典
84.         
85.         Raises:
86.             RuntimeError: 如果没有活动的 sandbox
87.         """
88.         if self._sandbox is None:
89.             raise RuntimeError("没有活动的 sandbox，请先创建")
90.         
91.         return {
92.             "sandbox_id": self._sandbox_id,
93.             "cdp_url": self._cdp_url,
94.             "vnc_url": self._vnc_url,
95.         }
96.    
97.     def get_cdp_url(self) -> Optional[str]:
98.         """获取 CDP URL"""
99.         return self._sandbox.get_cdp_url()
100.    
101.     def get_vnc_url(self) -> Optional[str]:
102.         """获取 VNC URL"""
103.         return self._sandbox.get_vnc_url()
104.    
105.     def get_sandbox_id(self) -> Optional[str]:
106.         """获取 Sandbox ID"""
107.         return self._sandbox_id
108.    
109.     def destroy(self) -> str:
110.         """
111.         销毁当前的 sandbox 实例
112.         
113.         Returns:
114.             str: 操作结果描述
115.         """
116.         if self._sandbox is None:
117.             return "没有活动的 sandbox"
118.         
119.         try:
120.             sandbox_id = self._sandbox_id
121.             
122.             # 尝试销毁 sandbox
123.             if hasattr(self._sandbox, 'delete'):
124.                 self._sandbox.delete()
125.             elif hasattr(self._sandbox, 'stop'):
126.                 self._sandbox.stop()
127.             elif hasattr(self._sandbox, 'destroy'):
128.                 self._sandbox.destroy()
129.             
130.             # 清理状态
131.             self._sandbox = None
132.             self._sandbox_id = None
133.             self._cdp_url = None
134.             self._vnc_url = None
135.             
136.             return f"Sandbox 已销毁: {sandbox_id}"
137.         
138.         except Exception as e:
139.             # 即使销毁失败，也清理本地状态
140.             self._sandbox = None
141.             self._sandbox_id = None
142.             self._cdp_url = None
143.             self._vnc_url = None
144.             return f"销毁 Sandbox 时出错: {str(e)}"
145.    
146.     def is_active(self) -> bool:
147.         """检查 sandbox 是否活跃"""
148.         return self._sandbox is not None
149.    
150.     def __enter__(self):
151.         """上下文管理器入口"""
152.         return self
153.    
154.     def __exit__(self, exc_type, exc_val, exc_tb):
155.         """上下文管理器退出，自动销毁"""
156.         self.destroy()
157.         return False
160. # 全局单例（可选，用于简单场景）
161. _global_manager: Optional[SandboxManager] = None
164. def get_global_manager() -> SandboxManager:
165.     """获取全局 SandboxManager 单例"""
166.     global _global_manager
167.     if _global_manager is None:
168.         _global_manager = SandboxManager()
169.     return _global_manager
172. def reset_global_manager():
173.     """重置全局 SandboxManager"""
174.     global _global_manager
175.     if _global_manager:
176.         _global_manager.destroy()
177.     _global_manager = None

复制代码

关键功能：

• 创建 Sandbox: 使用 AgentRun SDK 创建浏览器 Sandbox
  
• 获取连接信息: 自动获取 CDP URL 和 VNC URL，支持多种属性名兼容
  
• 生命周期管理: 提供销毁方法，确保资源正确释放
  

步骤 4: 创建 LangChain Tools 和 Agent

创建 langchain_agent.py 文件，定义 LangChain tools 并创建 Agent。核心代码如下：
[code]"""LangChain Agent 和 Tools 注册模块负责创建 LangChain Agent，注册 Sandbox 相关的 tools，并集成 VNC 可视化。本模块使用 sandbox_manager.py 中封装的 SandboxManager 来管理 sandbox 生命周期。"""import osfrom dotenv import load_dotenvfrom langchain.tools import toolfrom langchain_openai import ChatOpenAIfrom langchain.agents import create_agentfrom pydantic import BaseModel, Field# 导入 sandbox 管理器from sandbox_manager import SandboxManager# 加载环境变量load_dotenv()# 全局 sandbox 管理器实例（单例模式）_sandbox_manager: SandboxManager | None = Nonedef get_sandbox_manager() -> SandboxManager:    """获取 sandbox 管理器实例（单例模式）"""    global _sandbox_manager    if _sandbox_manager is None:        _sandbox_manager = SandboxManager()    return _sandbox_manager# ============ LangChain Tools 定义 ============@tooldef create_browser_sandbox(    template_name: str = None,    idle_timeout: int = 3000) -> str:    """创建或获取一个浏览器 sandbox 实例。        当需要访问网页、执行浏览器操作时，首先需要创建 sandbox。    创建成功后，会返回 sandbox 信息，包括 VNC URL 用于可视化。        Args:        template_name: Sandbox 模板名称，如果不提供则从环境变量 BROWSER_TEMPLATE_NAME 读取        idle_timeout: 空闲超时时间（秒），默认 3000 秒        Returns:        Sandbox 信息字符串，包括 ID、CDP URL、VNC URL    """    try:        manager = get_sandbox_manager()        # 如果 template_name 为空字符串，转换为 None 以便从环境变量读取        if template_name == "":            template_name = None        info = manager.create(template_name=template_name, idle_timeout=idle_timeout)                result = f"""✅ Sandbox 创建成功！
来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！