pip install browsergym

[!警告] BrowserGym 的目的是提供一个开放、易用且可扩展的框架，以加速网络智能体研究领域的发展。 它并非面向消费者的成品，请谨慎使用！

[!提示] 🚀 快来查看 AgentLab✨ 吧！ 这是一个无缝衔接的框架，可在 BrowserGym 的所有基准上实现、测试和评估您的网络智能体。

https://github.com/ServiceNow/BrowserGym/assets/26232819/e0bfc788-cc8e-44f1-b8c3-0d1114108b85

示例：GPT4-V 智能体执行开放式任务（顶行，聊天交互），以及 WebArena 和 WorkArena 任务（底行）。

BrowserGym 默认包含以下基准：

• MiniWoB
• WebArena
• WebArenaVerified
• VisualWebArena
• WorkArena
• AssistantBench
• WebLINX（静态基准）
• OpenApps
• TimeWarp

使用 BrowserGym 设计新的网络基准非常简单，只需继承 AbstractBrowserTask 类即可。

🛠️ 设置

要使用 browsergym，安装以下任一包：

pip install browsergym  # （推荐）包含以下所有内容
pip install browsergym-experiments  # 实验工具（智能体、循环、基准）+ 包含以下所有内容
pip install browsergym-core  # 仅核心功能（无基准，只有开放式任务）
pip install browsergym-miniwob  # 核心 + miniwob
pip install browsergym-webarena  # 核心 + webarena
pip install browsergym-webarena-verified  # 核心 + webarena_verified
pip install browsergym-visualwebarena  # 核心 + visualwebarena
pip install browsergym-workarena  # 核心 + workarena
pip install browsergym-assistantbench  # 核心 + assistantbench
pip install weblinx-browsergym  # 核心 + weblinx
pip install browsergym-timewarp  # 核心 + timewarp 

然后通过运行以下命令设置 Playwright：

playwright install chromium

最后，每个基准都有其特定的设置步骤，需要额外操作才能完成。

• 对于 MiniWoB++，请参阅 miniwob/README.md
• 对于 WebArena，请参阅 webarena/README.md
• 对于 WebArenaVerified，请参阅 webarena_verified/README.md
• 对于 VisualWebArena，请参阅 visualwebarena/README.md
• 对于 WorkArena，可参考 WorkArena
• 对于 AssistantBench，可参考 assistantbench/README.md
• 对于 OpenApps，可参考 OpenApps 文档
• 对于 TimeWarp，可参考 timewarp/README.md

🏗️ 开发环境设置

若要在本地开发环境中安装 browsergym，可使用以下命令：

git clone git@github.com:ServiceNow/BrowserGym.git
cd BrowserGym
make install

欢迎各位贡献！😊

🏋 使用方法

在交互式开放式任务上运行智能体的样板代码：

import gymnasium as gym
import browsergym.core  # 将开放式任务注册为 Gym 环境

# 启动开放式环境
env = gym.make(
    "browsergym/openended",
    task_kwargs={"start_url": "https://www.google.com/"},  # 起始网址
    wait_for_user_message=True,  # 每次智能体向聊天发送消息后等待用户回复
)
# 运行环境与智能体的交互循环，直到结束
obs, info = env.reset()
while True:
    action = ...  # 在此处实现您的智能体
    obs, reward, terminated, truncated, info = env.step(action)
    if terminated 或 truncated:
        break
# 关闭环境
env.close()

MiniWoB

import gymnasium as gym
import browsergym.miniwob  # 将 MiniWoB 任务注册为 Gym 环境

# 启动 MiniWoB 任务
env = gym.make("browsergym/miniwob.choose-list")
...

# 列出所有可用的 MiniWoB 任务
env_ids = [id for id in gym.envs.registry.keys() if id.startswith("browsergym/miniwob")]
print("\n".join(env_ids))

WorkArena

import gymnasium as gym
import browsergym.workarena  # 将 WorkArena 任务注册为 Gym 环境

# 启动 WorkArena 任务
env = gym.make("browsergym/workarena.servicenow.order-ipad-pro")
...

# 列出所有可用的 WorkArena 任务
env_ids = [id for id in gym.envs.registry.keys() if id.startswith("browsergym/workarena")]
print("\n".join(env_ids))

WebArena

import gymnasium as gym
import browsergym.webarena  # 将 WebArena 任务注册为 Gym 环境

# 启动 WebArena 任务
env = gym.make("browsergym/webarena.310")
...

# 列出所有可用的 WebArena 任务
env_ids = [id for id in gym.envs.registry.keys() if id.startswith("browsergym/webarena")]
print("\n".join(env_ids))

VisualWebArena

import gymnasium as gym
import browsergym.webarena  # 将 WebArena 任务注册为 Gym 环境

# 启动 VisualWebArena 任务
env = gym.make("browsergym/visualwebarena.721")
...

# 列出所有可用的 VisualWebArena 任务
env_ids = [id for id in gym.envs.registry.keys() if id.startswith("browsergym/visualwebarena")]
print("\n".join(env_ids))

AssistantBench

import gymnasium as gym
import browsergym.workarena  # 将 AssistantBench 任务注册为 Gym 环境

# 启动 AssistantBench 任务
env = gym.make("browsergym/assistantbench.validation.3")
...

# 列出所有可用的 assistantbench 任务
env_ids = [id for id in gym.envs.registry.keys() if id.startswith("browsergym/workarena")]
print("\n".join(env_ids))

OpenApps

from open_apps.apps.start_page.main import app  # 需要导入应用才能提供服务
from open_apps.launcher import OpenAppsLauncher

config = ... # 配置包含任务、智能体、环境和服务器配置的命名空间

launcher = OpenAppsLauncher(config)
launcher.launch()

TimeWarp

import gymnasium as gym
import browsergym.timewarp  # 注册 TimeWarp 任务为 Gym 环境

# 启动一个 TimeWarp 任务
env = gym.make("browsergym/timewarp.1")
...

# 列出所有可用的 TimeWarp 任务
env_ids = [id for id in gym.envs.registry.keys() if id.startswith("browsergym/timewarp")]
print("\n".join(env_ids))

💻 演示

如果你想在 BrowserGym 中体验演示智能体，请按照以下步骤操作：

# 使用 Conda 设置
conda env create -f demo_agent/environment.yml
conda activate demo_agent

# 或者使用 pip 设置
pip install -r demo_agent/requirements.txt

# 然后下载 Playwright 的浏览器
playwright install chromium

我们的演示智能体使用 openai 作为后端，请确保设置好你的 OPENAI_API_KEY。

按如下方式启动演示智能体：

# 开放式（交互式聊天模式）
python demo_agent/run_demo.py --task_name openended --start_url https://www.google.com

# miniwob
python demo_agent/run_demo.py --task_name miniwob.click-test

# workarena
python demo_agent/run_demo.py --task_name workarena.servicenow.order-standard-laptop

# webarena
python demo_agent/run_demo.py --task_name webarena.4

# visualwebarena
python demo_agent/run_demo.py --task_name visualwebarena.398

你可以通过更改 model_name 来选择你喜欢的语言模型（默认使用 gpt-4o-mini），或者通过添加 use_screenshot 参数来为视觉语言模型生成截图，还有更多自定义选项！

python demo_agent/run_demo.py --help

🌐 生态系统

• AgentLab：无缝运行智能体进行基准测试，并收集与分析轨迹数据。
• WorkArena(++)：针对 ServiceNow 平台上的 Web 智能体的基准测试平台。
• WebArena：基于自托管域名的真实 Web 任务基准测试平台。
• VisualWebArena：基于自托管域名的真实视觉 Web 任务基准测试平台。
• MiniWoB(++)：包含超过 100 个在合成网页上执行的 Web 任务集合。
• WebLINX：真实世界 Web 交互轨迹数据集。
• AssistantBench：针对开放网络中真实且耗时任务的基准测试平台。
• DoomArena：用于 AI 智能体安全测试的框架，支持从 Browsergym 环境中向网页注入攻击。

🌟 贡献者

📝 引用本工作

如果你希望引用 BrowserGym，请使用以下两个 BibTeX 条目：

@article{
    chezelles2025browsergym,
    title={The BrowserGym Ecosystem for Web Agent Research},
    author={Thibault Le Sellier de Chezelles and Maxime Gasse and Alexandre Lacoste and Massimo Caccia and Alexandre Drouin and L{\'e}o Boisvert and Megh Thakkar and Tom Marty and Rim Assouel and Sahar Omidi Shayegan and Lawrence Keunho Jang and Xing Han L{\`u} and Ori Yoran and Dehan Kong and Frank F. Xu and Siva Reddy and Graham Neubig and Quentin Cappart and Russ Salakhutdinov and Nicolas Chapados},
    journal={Transactions on Machine Learning Research},
    issn={2835-8856},
    year={2025},
    url={https://openreview.net/forum?id=5298fKGmv3},
    note={Expert Certification}
}

@inproceedings{workarena2024,
    title = {{W}ork{A}rena: How Capable are Web Agents at Solving Common Knowledge Work Tasks?},
    author = {Drouin, Alexandre and Gasse, Maxime and Caccia, Massimo and Laradji, Issam H. and Del Verme, Manuel and Marty, Tom and Vazquez, David and Chapados, Nicolas and Lacoste, Alexandre},
    booktitle = {Proceedings of the 41st International Conference on Machine Learning},
    pages = {11642--11662},
    year = {2024},
    editor = {Salakhutdinov, Ruslan and Kolter, Zico and Heller, Katherine and Weller, Adrian and Oliver, Nuria and Scarlett, Jonathan and Berkenkamp, Felix},
    volume = {235},
    series = {Proceedings of Machine Learning Research},
    month = {21--27 Jul},
    publisher = {PMLR},
    url = {https://proceedings.mlr.press/v235/drouin24a.html},
}

以下是它们的使用示例：

我们在实验中使用了 BrowserGym 框架 \cite{workarena2024,chezelles2025browsergym}。

轨迹数据

《BrowserGym 生态系统用于 Web 智能体研究》论文中的轨迹数据可在 Huggingface 上获取。

BrowserGym 快速上手指南

BrowserGym 是一个开放、易用且可扩展的框架，旨在加速 Web 智能体（Web Agent）的研究。它基于 Gymnasium 接口，集成了 MiniWoB、WebArena、WorkArena 等多个主流基准测试。

注意：本工具专为科研设计，非消费级产品，请谨慎使用。

环境准备

在开始之前，请确保满足以下系统要求：

• 操作系统：Linux, macOS 或 Windows (推荐 Linux)
• Python 版本：3.8 及以上
• 依赖项：
  • pip 包管理工具
  • Playwright 浏览器自动化库

安装步骤

1. 安装核心库

推荐使用 pip 安装完整版（包含所有基准测试支持），也可根据需求选择特定模块。

# 推荐：安装完整版（包含所有基准测试）
pip install browsergym

# 或者仅安装核心功能（不含具体基准测试）
pip install browsergym-core

# 或者按需安装特定基准测试（例如 MiniWoB）
pip install browsergym-miniwob

国内加速提示：如果下载速度较慢，可使用清华或阿里镜像源：

pip install browsergym -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 配置 Playwright 浏览器

安装完成后，必须下载 Playwright 所需的浏览器内核（此处以 Chromium 为例）：

playwright install chromium

3. 特定基准测试的额外配置

部分基准测试（如 WebArena, WorkArena）需要额外的环境搭建（如部署本地服务器）。请参考各子模块的 README.md 进行配置：

• MiniWoB: browsergym/miniwob/README.md
• WebArena: browsergym/webarena/README.md
• WorkArena: WorkArena GitHub

基本使用

BrowserGym 完全兼容 gymnasium 接口。以下是运行一个开放式任务（Open-ended task）的最简示例。

示例：运行开放式任务

此示例将启动一个浏览器环境，访问 Google，并等待智能体执行操作。

import gymnasium as gym
import browsergym.core  # 注册开放式任务环境

# 启动环境
env = gym.make(
    "browsergym/openended",
    task_kwargs={"start_url": "https://www.google.com/"},  # 起始网址
    wait_for_user_message=True,  # 每次交互后等待用户消息（调试用）
)

# 重置环境
obs, info = env.reset()

# 运行主循环
while True:
    # TODO: 在此处实现你的智能体逻辑
    # action = your_agent(obs)
    action = ""  # 占位符
    
    # 执行动作
    obs, reward, terminated, truncated, info = env.step(action)
    
    if terminated or truncated:
        break

# 关闭环境
env.close()

示例：运行特定基准测试 (MiniWoB)

加载并运行具体的基准测试任务非常简单，只需更改环境名称即可。

import gymnasium as gym
import browsergym.miniwob  # 注册 MiniWoB 任务

# 启动特定的 MiniWoB 任务
env = gym.make("browsergym/miniwob.choose-list")

obs, info = env.reset()
# ... 运行你的智能体循环 ...
env.close()

你可以列出所有可用的任务 ID：

import gymnasium as gym
import browsergym.miniwob

env_ids = [id for id in gym.envs.registry.keys() if id.startswith("browsergym/miniwob")]
print("\n".join(env_ids))

进阶：运行官方演示智能体

如果你想快速体验内置的 Demo 智能体（基于 OpenAI API），可以按以下步骤操作：

1. 安装依赖：

   pip install -r demo_agent/requirements.txt
   playwright install chromium
   

2. 设置 API Key：

   export OPENAI_API_KEY=your_key_here
   

3. 运行演示：

   # 运行开放式交互任务
   python demo_agent/run_demo.py --task_name openended --start_url https://www.google.com
   
   # 运行 MiniWoB 任务
   python demo_agent/run_demo.py --task_name miniwob.click-test