文档中心>云函数>AI 应用>Agent 执行引擎>浏览器沙箱应用(内测中)

浏览器沙箱应用(内测中)

最近更新时间:2025-11-21 17:11:12

我的收藏
本文介绍如何在 Agent 执行引擎部署浏览器沙箱应用,提供安全、隔离的浏览器环境,让您能够与 Web 应用程序交互,同时最大限度地降低系统的潜在风险。它在 AI 运行时容器化环境中运行,并将 Web 活动与您的本地系统隔离。
说明:
该功能处于内测阶段,如需使用,请提交 内测申请
该功能目前仅支持在香港地域使用。
浏览器沙箱应用镜像来源于社区开源软件镜像 steel-browser,本平台不参与维护。若您使用此镜像:
您有义务遵守相应的第三方规则,包括但不限于任何可能附随的开源软件许可协议。
在用于生产环境之前,您应当进行充分的验证和测试,并主动修复可能存在的缺陷。
如果使用过程中对 steel-browser 项目有更多需求,需要提交 issue 由社区支持 GitHub · Where software is built

前置依赖

操作步骤

步骤一:创建浏览器沙箱应用

1. 登录 Serverless 控制台,单击左侧导航栏的 Agent
2. Serverless AI 运行时页面上的沙箱工具区域,单击创建应用,进入应用创建流程。

3. 基础配置版块:
3.1 填入应用名称:应用的唯一标识,不可重复,创建后不可修改。
3.2 选择地域:资源必须归属于某个地域。

4. 环境配置版块:
4.1 选择内存:设置资源类型对应的规格,当前仅支持 CPU 不同内存配置,详情请参见 函数算力支持
4.2 添加环境变量,在配置中定义的环境变量可在函数运行时从环境中获取到。详情请参见 环境变量

5. 网络配置版块,配置函数网络访问权限:
公网访问:默认未启用,如果需要访问公网资源,则需要启用。
私有网络:启用后,应用可以访问同一个私有网络下的资源。

6. 日志配置版块:启用日志投递,可将函数运行日志实时投递到指定位置。详情请参见 日志投递配置

7. 隔离、并发配置版块:配置实例安全隔离单实例并发模式

7.1 实例安全隔离:
如果启用,保证一个沙箱独占一个实例,沙箱销毁时,实例也销毁。
如果不启用,多个沙箱可能共享一个实例。
7.2 配置基于会话单实例并发模式,该配置主要用于标记客户端请求以哪种方式携带沙箱 ID、配置沙箱生命周期、底层实例支持的沙箱并发数和请求,其中本应用中“会话”的配置对应的是“沙箱”的配置。具体配置项说明如下:
配置项
说明
示例
会话 Key 来源
标记客户端请求以哪种方式携带沙箱 ID,系统根据此标记来决定要调度到某个沙箱上。可选项:Http Header、Cookie、Query String,三选一。不同选项支持场景说明如下:
Http Header
通过 HTTP 请求头传递客户端会话标识,后台确保相同标识的请求被路由到同一个沙箱。适用于 WebSocket 协议、gRPC 协议、HTTP 协议。支持客户端自定义沙箱 ID,也支持服务端生成。
Cookie
将携带相同 Cookie 信息的请求路由到同一个沙箱。支持客户端生成沙箱 ID,也支持服务端生成。
Query String
将携带相同 Query String 信息的请求路由到同一个沙箱,需要客户端生成沙箱 ID。
Http Header
会话 Key 名称
1. Key 用途及命名规则
用途:沙箱的唯一标识名称。
命名要求:必须以字母开头;非首字母可包含数字、字母、下划线(_)、中划线(-);长度限制5-40 个字符(含边界值)。
2. Key 对应 Value(沙箱 ID )生成逻辑及字符要求:
生成逻辑:
来源为 Http Header、Cookie:支持客户端在首次调用时自主生成 Value;若客户端未生成,系统将自动生成。
来源为 QueryString:首次 Value 需由客户端生成。
字符要求:
含数字、字母、下划线(_)、中划线(-)长度限制128个字节。
sandbox-id
会话最长生命周期
从沙箱创建、使用到最终销毁的全过程,单位秒。超过生命周期后,服务端将自动销毁沙箱。最长可设置7天,默认21600秒。
21600秒
会话最长空闲时间
用户在一段时间内没有进行任何操作,导致沙箱进入空闲状态,单位秒。最长不得超过会话最长生命周期,默认1800秒。超过最长空闲(Idle)时间后,服务端将按照“会话空闲超时处理策略”处理沙箱。
1800秒
会话空闲超时处理策略
如果您开启了“实例安全隔离”,会话空闲超时处理策略可选自动销毁或者自动暂停。
如果您没有开启“实例安全隔离”,会话空闲超时处理策略默认自动销毁。
自动销毁
单实例最大并发会话数
单实例在同一时间内支持的最大沙箱数,默认值为20,最大支持100。
20
单实例最大并发请求数
单实例在同一时间内支持的最大请求数,默认为10,最大支持100。
10
8. 单击提交,启动应用的部署。
9. 应用部署完成后,在应用详情页面,可以获得访问地址。如果想从公网访问,建议您配置 自定义域名

步骤二:生成浏览器沙箱实例

1. 应用部署完成后,在应用详情页面,可以获得应用访问地址。

2. 在客户端指定沙箱 ID,生成浏览器沙箱实例:
from steel import Steel

def create_browser_sandbox():
# 用您的浏览器沙箱应用 URL 替换 {$URL}
sandbox_url = "{$应用URL}"
# 客户端生成沙箱 ID
sandbox_id = "sandbox-id-123456"
# 通过指定沙箱 ID x-ssid 生成沙箱
client = Steel(base_url = sandbox_url)
session = client.sessions.create(
extra_headers={
'sandbox-id': sandbox_id
}
)
ws_url = session.websocketUrl
print(f"✅ Browser Sandbox created: {sandbox_id}")
print(f"🔗 WebSocket地址: {ws_url}")
if __name__ == "__main__":
create_browser_sandbox()
返回结果如下:
✅ 浏览器沙箱已创建: sandbox-id-123456
🔗 WebSocket地址: ws://******.ap-******.tencentscf.com/

使用浏览器

通过 Playwright 使用浏览器

以下完整示例演示如何在浏览器中访问腾讯云官网:
前置依赖:参考步骤一创建浏览器沙箱,该沙箱的会话配置如下(您也可以改成其他方式,代码需要对应修改):
会话 Key 来源:HTTP Header
会话 Key 名称:sandbox-id
from steel import Steel
from playwright.sync_api import sync_playwright
import time

def playwright_demo():
# 创建浏览器沙箱实例
# 用您的浏览器沙箱应用 URL 替换
sandbox_url = "https://******.ap-hongkong.tencentscf.com"
# 客户端生成沙箱 ID
sandbox_id = "sandbox-id-12345678"
client = Steel(base_url = sandbox_url)
session = client.sessions.create(
extra_headers={
'sandbox-id': sandbox_id
}
)
ws_url = session.websocketUrl
print(f"✅ 浏览器沙箱已创建: {sandbox_id}")
print(f"🔗 WebSocket地址: {ws_url}")
# 完成浏览器沙箱实例创建
# 启动 playwright
playwright = sync_playwright().start()
browser = playwright.chromium.connect_over_cdp(ws_url, headers={
'sandbox-id': sandbox_id
})
print("✅ 连接到浏览器")

# 创建一个新的页面
context = browser.contexts[0]
page = context.new_page()
# 访问腾讯云官网
page.goto("https://cloud.tencent.com/")
print(f"✅ 访问腾讯云官网:{page.url}")
# 获取页面标题
print(f"📄 页面标题: {page.title()}")

# 关闭浏览器连接
browser.close()


if __name__ == "__main__":
playwright_demo()
返回结果如下:
✅ 浏览器沙箱已创建: sandbox-id-12345678
🔗 WebSocket地址: ws://******.ap-******.tencentscf.com/
✅ 连接到浏览器
✅ 访问腾讯云官网:https://cloud.tencent.com/
📄 页面标题: 腾讯云 产业智变·云启未来 - 腾讯

通过 Puppeteer 使用浏览器

以下完整示例演示如何在浏览器中访问腾讯云官网:
前置依赖:参考步骤一创建浏览器沙箱,该沙箱的会话配置如下:
会话 Key 来源:Query String
会话 Key 名称:sandboxId

import asyncio
from pyppeteer import connect
from steel._client import Steel


sandbox_url = '******.ap-hongkong.tencentscf.com'
sandbox_id = 'd45ea6f6-c5b2-47b5-9a42-4237d8647945'

async def puppeteer_demo():

# 浏览器沙箱 初始化
client = Steel(base_url=f'http://{sandbox_url}', default_query={'sandboxId':sandbox_id})
session = client.sessions.create(
extra_query={
'sandboxId': sandbox_id
}
)
cdp_url = f'{session.websocketUrl}?sandboxId={sandbox_id}'
print(f"✅ 浏览器沙箱已创建: {sandbox_id}")
print(f"🔗 CDP 地址: {cdp_url}")
# 完成浏览器沙箱实例创建

try:
browser = await connect({
'browserWSEndpoint': cdp_url,
'defaultViewport': None
})
print('✅ 通过 CDP 连接到浏览器')

page = await browser.newPage()

await page.goto('https://cloud.tencent.com/')
print(f"✅ 访问腾讯云官网:{page.url}")
print(f"📄 页面标题: {await page.title()}")

await browser.close()
except Exception as error:
print('Error:', str(error))

if __name__ == "__main__":
asyncio.run(puppeteer_demo())
返回结果如下:

✅ 浏览器沙箱已创建: d45ea6f6-c5b2-47b5-9a42-4237d8647945
🔗 CDP 地址: ws://******.ap-hongkong.tencentscf.com/?sandboxId=d45ea6f6-c5b2-47b5-9a42-4237d8647945
✅ 通过 CDP 连接到浏览器
✅ 访问腾讯云官网:https://cloud.tencent.com/
📄 页面标题: 腾讯云 产业智变·云启未来 - 腾讯

在 browser-use agent 集成浏览器沙箱工具

以下完整示例演示如何在 browser-use agent 集成浏览器沙箱,查询天气信息:
前置依赖:参考步骤一创建浏览器沙箱,该沙箱的会话配置如下:
会话 Key 来源:Query String
会话 Key 名称:sandboxId
from browser_use import Agent, BrowserSession
from browser_use.llm import ChatDeepSeek
from steel._client import Steel
from dotenv import load_dotenv
import asyncio
import os


# 读取 DEEPSEEK_API_KEY 配置
load_dotenv()

# 浏览器沙箱配置
sandbox_url = '******.ap-hongkong.tencentscf.com'
sandbox_id = 'd43ea6f6-c5b2-47b5-9a42-4237d8647945'
cdp_url = f'ws://{sandbox_url}?sandboxId={sandbox_id}'

# 模型服务配置
deepseek_api_key = os.getenv('DEEPSEEK_API_KEY')


async def main():

# 模型服务 初始化
llm = ChatDeepSeek(
base_url='https://api.deepseek.com/v1',
model='deepseek-chat',
api_key=deepseek_api_key,
)

# 浏览器沙箱 初始化
client = Steel(base_url=f'http://{sandbox_url}', default_query={'sandboxId':sandbox_id})
session = client.sessions.create(session_id=sandbox_id)
browser_session = BrowserSession(cdp_url=cdp_url)

# 任务
task = "打开百度,查询深圳天气"

# Agent 初始化
agent = Agent(task=task,
llm=llm,
browser_session=browser_session)

# 执行任务
await agent.run()


if __name__ == "__main__":
asyncio.run(main())

返回结果如下:
INFO [service] Using anonymized telemetry, see https://docs.browser-use.com/development/telemetry.
WARNING [Agent] ⚠️ DeepSeek models do not support use_vision=True yet. Setting use_vision=False for now...
INFO [Agent] 🎯 Task: 打开百度,查询深圳天气
INFO [Agent] 📦 Newer version available: 0.9.0 (current: 0.8.1). Upgrade with: uv add browser-use@0.9.0
INFO [Agent] Starting a browser-use agent with version 0.8.1, with provider=deepseek and model=deepseek-chat
INFO [Agent]

INFO [Agent] 📍 Step 1:
INFO [Agent] ❔ Eval: No previous action to evaluate - this is the first step.
INFO [Agent] 🧠 Memory: Starting fresh browser session. Need to navigate to Baidu and search for Shenzhen weather information.
INFO [Agent] 🎯 Next goal: Navigate to Baidu's homepage to begin the search process.
INFO [Agent] ▶️ navigate: url: https://www.baidu.com, new_tab: False
INFO [tools] 🔗 Navigated to https://www.baidu.com
INFO [Agent]

INFO [Agent] 📍 Step 2:
INFO [Agent] 👍 Eval: Successfully navigated to Baidu's homepage as the first step.
INFO [Agent] 🧠 Memory: Currently on Baidu homepage, ready to search for Shenzhen weather information.
INFO [Agent] 🎯 Next goal: Input '深圳天气' into the search box and click search to get weather information.
INFO [Agent] ▶️ [1/2] input: index: 16, text: 深圳天气, clear: True
INFO [BrowserSession] ⌨️ Typed "深圳天气" into element with index 16
INFO [Agent] ▶️ [2/2] click: index: 41
INFO [tools] 🖱️ Clicked element
INFO [Agent]

INFO [Agent] 📍 Step 3:
INFO [Agent] 👍 Eval: Successfully searched for Shenzhen weather on Baidu and obtained comprehensive weather information.
INFO [Agent] 🧠 Memory: Successfully completed the user request by navigating to Baidu, searching for '深圳天气', and retrieving detailed weather information including current conditions (19-24°C, cloudy), wind conditions, air quality, and extended forecasts.
INFO [Agent] 🎯 Next goal: Present the weather information to the user and complete the task.
INFO [Agent] ▶️ done: text: 已成功在百度查询深圳天气信息:

**当前天气状况(14:35更新)**
- 地点:深圳
- 天气:多云
- 温度:19~24°C
- 风力:东北风3级
- 空气质量:38 优

**今日预报**
- 当前温度:19°C
- 天气状况:多云
- 体感温度:24°C(人体感觉较为舒适)
- 湿度:56..., success: True, files_to_display: []
INFO [Agent]
📄 Final Result:
已成功在百度查询深圳天气信息:

**当前天气状况(14:35更新)**
- 地点:深圳
- 天气:多云
- 温度:19~24°C
- 风力:东北风3级
- 空气质量:38 优

**今日预报**
- 当前温度:19°C
- 天气状况:多云
- 体感温度:24°C(人体感觉较为舒适)
- 湿度:56%
- 紫外线指数:偏弱
- 降水量:0.0毫米

**生活气象指数**
- 穿衣:外套类(舒适)
- 感冒:少发(无需特别防护)
- 洗车:较适宜(未来一天无雨)
- 化妆:控油(露质面霜打底)

**日出日落时间**
- 日出:06:24
- 日落:17:52

已成功完成在百度查询深圳天气的任务。


INFO [Agent] ✅ Task completed successfully

社区完整 API 说明

社区完整 API 列表请查阅 Steel API 文档,使用 API 时,需要将 endpoint 替换成应用的访问地址,并根据您指定方式(会话 Key 来源、会话 Key 名称)携带上沙箱 ID。
如果通过 SDK 调用,需要先安装 steel-sdk ,支持 Node 和 Python:
Node:使用时需要将访问地址 baseURL 替换为应用的 URL。SDK 使用详见 Node SDK 指引
Python:使用时需要将访问地址 base_url 替换为应用的 URL。SDK 使用详见 Python SDK 指引