🛠️ 设置  |  🤖 助手  |  🚀 启动实验  |  🔍 分析结果  | 
🏆 排行榜  |  🤖 构建你的智能体  |  ↻ 可重复性  |  💪 BrowserGym

演示解决任务：:

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

AgentLab是一个用于在各种由BrowserGym支持的 基准测试上开发和评估智能体的框架。更多详细信息请参阅我们的 BrowserGym生态系统论文。

AgentLab的特点：

• 使用ray轻松进行大规模并行智能体实验
• 为基于BrowserGym构建智能体提供的基础组件
• 统一的LLM API，适用于OpenRouter、OpenAI、Azure或使用TGI自托管的模型
• 运行WebArena等基准测试的首选方式
• 多种可重复性功能
• 统一的排行榜

🎯 支持的基准测试

🛠️ 设置AgentLab

AgentLab需要Python 3.11或3.12。

pip install agentlab

如果尚未完成，请安装Playwright：

playwright install

请务必按照设置列中提供的说明准备所需的基准测试。

export AGENTLAB_EXP_ROOT=<实验结果根目录>  # 默认为$HOME/agentlab_results
export OPENAI_API_KEY=<你的OpenAI API密钥> # 如果使用OpenAI模型

export OPENROUTER_API_KEY=<你的OpenRouter API密钥> # 如果使用OpenRouter模型

export AZURE_OPENAI_API_KEY=<你的Azure API密钥> # 如果使用Azure模型
export AZURE_OPENAI_ENDPOINT=<你的端点> # 如果使用Azure模型

🤖 UI-助手

使用助手为你工作（需自行承担费用和风险）。

agentlab-assistant --start_url https://www.google.com

尝试你自己的智能体：

agentlab-assistant --agent_config="module.path.to.your.AgentArgs"

🚀 启动实验

# 导入你的智能体配置，该配置扩展了bgym.AgentArgs类

# 确保从 PYTHONPATH 中可访问的模块导入此对象，以便正确反序列化
from agentlab.agents.generic_agent import AGENT_4o_MINI 

from agentlab.experiments.study import make_study

study = make_study(
    benchmark="miniwob",  # 或 "webarena", "workarena_l1" ...
    agent_args=[AGENT_4o_MINI],
    comment="我的第一个研究",
)

study.run(n_jobs=5)

重新启动未完成或出错的任务

from agentlab.experiments.study import Study
study = Study.load("/path/to/your/study/dir")
study.find_incomplete(include_errors=True)
study.run()

请参阅 main.py 以使用各种选项启动实验。这就像一个懒惰的命令行界面，实际上更加方便。只需根据需要注释或取消注释所需行，或随意修改（但不要推送到仓库）。

作业超时

野生网络、Playwright 和 asyncio 的复杂性有时会导致作业挂起。这会使工作进程失效，直到研究被终止并重新启动。如果您按顺序运行作业或使用少量工作进程，这可能会使整个研究停滞，直到您手动终止并重新启动它。在 Ray 并行后端中，我们实现了一个系统，可以自动终止超过指定超时时间的作业。当任务挂起限制您的实验时，此功能尤为有用。

调试

为了调试，请以 n_jobs=1 运行实验，并使用 VSCode 的调试模式。这样可以在断点处暂停执行。

关于并行作业

一个代理处理一个任务对应于一个作业。进行消融研究或在数百个任务上进行多种子随机搜索，可能会生成超过 10,000 个作业。因此，高效的并行执行至关重要。代理通常会等待 LLM 服务器的响应或 Web 服务器的更新。因此，在一台计算机上，您可以并行运行 10–50 个作业，具体数量取决于可用的 RAM。

⚠️ (Visual)WebArena 注意事项：这些基准测试具有任务依赖关系，旨在尽量减少任务之间对实例的“污染”。例如，处理第 323 个任务的代理可能会改变实例状态，从而使第 201 个任务无法完成。为了解决这个问题，Ray 后端会考虑任务依赖关系，从而实现一定程度的并行性。在 WebArena 上，您可以禁用依赖关系以提高并行度，但这可能会降低 1–2% 的性能。

⚠️ (Visual)WebArena 实例重置：在评估代理之前，实例会自动重置，这一过程大约需要 5 分钟。当评估多个代理时，make_study 函数会返回一个 SequentialStudies 对象，以确保每个代理都能按顺序正确评估。AgentLab 目前不支持跨多个实例的评估，但您可以编写一个快速脚本来处理这种情况，或者向 AgentLab 提交拉取请求。为了获得更流畅的并行体验，建议使用 WorkArena 等基准测试。

🔍 分析结果

加载结果

类 ExpResult 提供了特定实验所有信息的惰性加载器。您可以使用 yield_all_exp_results 递归地查找目录中的所有结果。最后，load_result_df 会将所有汇总信息收集到一个数据框中。有关示例用法，请参阅 inspect_results.ipynb。

from agentlab.analyze import inspect_results

# 将研究中所有实验的汇总信息加载到数据框中
result_df = inspect_results.load_result_df("path/to/your/study")

# 加载第一个实验的详细结果
exp_result = bgym.ExpResult(result_df["exp_dir"][0])
第 0 步的截图 = exp_result.screenshots[0]
第 0 步的动作 = exp_result.steps_info[0].action

AgentXray

https://github.com/user-attachments/assets/06c4dac0-b78f-45b7-9405-003da4af6b37

在终端中执行：

agentlab-xray

您可以加载 AGENTLAB_EXP_ROOT 目录中以前或正在进行的实验，并在 Gradio 界面中可视化结果。

按照以下顺序选择：

• 您想要可视化的实验
• 如果有多个代理，请选择代理
• 任务
• 种子

选择完成后，您可以看到代理在给定任务上的操作轨迹。单击剖析图像以选择某个步骤，并观察代理采取的动作。

⚠️ 注意：Gradio 仍在开发中，经常会出现意外行为。目前看来，版本 5.5 运行正常。如果您不确定显示的信息是否正确，请刷新页面并再次选择您的实验。

🏆 排行榜

所有基准测试的官方统一 排行榜。

正在开展更多使用 GenericAgent 的参考实验。我们也在开发代码，以便自动将研究推送到排行榜。

🤖 实现新代理

可以从 agentlab/agents/most_basic_agent/most_basic_agent.py 中的 MostBasicAgent 获取灵感。为了更好地与工具集成，务必在 AgentArgs API 和扩展的 bgym.AbstractAgentArgs 中实现大多数功能。

如果您认为您的代理应直接纳入 AgenLab，请告知我们，我们可以将其添加到 agentlab/agents/ 目录中，并以您的代理名称命名。

↻ 可重复性

在动态基准测试中评估代理时，有几个因素会影响结果的可重复性。

影响可重复性的因素

• 软件版本：Playwright 或软件栈中任何包的不同版本都可能影响基准测试或代理的行为。
• 基于 API 的 LLM 默默变化：即使版本固定，LLM 也可能被更新，例如为了融入最新的网络知识。
• 实时网站：
  • WorkArena：演示实例大多固定在特定版本，但 ServiceNow 有时会推送一些小的修改。
  • AssistantBench 和 GAIA：这些基准测试依赖于代理在开放网络中导航。体验可能会因国家或地区而异，某些网站默认语言可能不同。
• 随机性代理：将 LLM 的温度设置为 0 可以减少大部分随机性。
• 非确定性任务：对于固定的种子，变化应该很小

可复现性功能

• Study 包含一个关于可复现性的信息字典，包括基准测试版本、软件包版本和提交哈希值。
• Study 类允许自动将您的结果上传到 reproducibility_journal.csv。这使得填充大量参考点变得更加容易。要使用此功能，您需要先 git clone 该仓库，并通过 pip install -e . 进行安装。
• 排行榜中的已复现结果。对于可复现的智能体，我们鼓励用户尝试复现其结果，并将其上传到排行榜。排行榜中有一个特殊列，用于记录某个智能体在特定基准测试上的所有已复现结果。
• ReproducibilityAgent：您可以运行此智能体 来处理现有的研究，它会尝试在相同的任务种子上重新执行相同的操作。两次提示的可视化差异将在 AgentXray 的 AgentInfo HTML 选项卡中显示。您可以在某些任务上检查两次执行之间的具体变化。注意：此功能目前处于测试阶段，可能需要根据您自己的智能体进行一些调整。

变量

以下是 AgentLab 使用的相关环境变量列表：

• OPENAI_API_KEY：默认用于 OpenAI 的大语言模型。
• AZURE_OPENAI_API_KEY：默认用于 AzureOpenAI 的大语言模型。
• AZURE_OPENAI_ENDPOINT：用于指定您的 Azure 终端地址。
• OPENAI_API_VERSION：用于 Azure API 的版本号。
• OPENROUTER_API_KEY：用于 Openrouter API。
• AGENTLAB_EXP_ROOT：您希望存储实验结果的路径，默认为 ~/agentlab-results。
• AGENTXRAY_SHARE_GRADIO：启用后，AgentXRay 启动时会打开一个公共隧道。
• RAY_PUBLIC_DASHBOARD（true / false）：用于指定 Ray 仪表板是否应对外公开（0.0.0.0）或仅限本地访问（127.0.0.1）。
• RAY_DASHBOARD_PORT（整数）：用于指定 Ray 仪表板的访问端口。

其他

如果您希望更快地下载 Hugging Face 模型：

pip install hf-transfer
pip install torch
export HF_HUB_ENABLE_HF_TRANSFER=1

📝 引用本工作

如果您希望引用 AgentLab，请使用以下两个 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},
}

以下是它们的使用示例：

我们使用 AgentLab 框架来运行和管理我们的实验 \cite{workarena2024,chezelles2025browsergym}。

跟踪记录

《Web 代理研究的 BrowserGym 生态系统》论文中的跟踪记录可在 Huggingface 上获取。

AgentLab 快速上手指南

AgentLab 是一个用于开发和评估 Web 智能体（Web Agents）的开源框架，基于 BrowserGym 生态系统构建。它支持大规模并行实验、统一的 LLM API 接入以及多种主流基准测试（如 WebArena, WorkArena 等）。

注意：AgentLab 旨在加速科研而非作为消费级产品使用，请在受控环境中运行。

环境准备

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

• 操作系统：Linux, macOS 或 Windows (推荐 Linux)
• Python 版本：3.11 或 3.12
• 前置依赖：
  • pip 包管理工具
  • Playwright (用于浏览器自动化)

安装步骤

1. 安装 AgentLab

使用 pip 安装核心库：

pip install agentlab

2. 安装 Playwright 浏览器驱动

安装完成后，必须执行以下命令下载所需的浏览器内核：

playwright install

3. 配置环境变量

设置实验结果存储路径及所需的 LLM API 密钥。

# 设置实验结果根目录 (默认为 $HOME/agentlab_results)
export AGENTLAB_EXP_ROOT=<你的实验结果存放目录>

# 配置 OpenAI API Key (如果使用 OpenAI 模型)
export OPENAI_API_KEY=<你的 openai api key>

# 可选：配置 OpenRouter API Key
# export OPENROUTER_API_KEY=<你的 openrouter api key>

# 可选：配置 Azure OpenAI
# export AZURE_OPENAI_API_KEY=<你的 azure api key>
# export AZURE_OPENAI_ENDPOINT=<你的 endpoint>

提示：国内用户若访问 PyPI 或 HuggingFace 较慢，可配置相应的镜像源或代理加速。

4. 准备基准测试环境

根据你要使用的基准测试（Benchmark），参考 Supported Benchmarks 表格中的 Setup 链接进行额外配置。 例如，运行 WebArena 通常需要自行部署 Docker 环境；而 WorkArena 可使用官方提供的 Demo 实例。

基本使用

模式一：启动 UI 助手 (交互式体验)

直接启动一个图形化助手界面，让智能体在指定网页上执行任务。

# 启动默认助手，打开 Google
agentlab-assistant --start_url https://www.google.com

# 启动自定义配置的智能体
agentlab-assistant --agent_config="module.path.to.your.AgentArgs"

模式二：运行实验 (代码方式)

创建一个 Python 脚本（例如 run_study.py），定义研究任务并运行。

from agentlab.agents.generic_agent import AGENT_4o_MINI 
from agentlab.experiments.study import make_study

# 创建研究任务
study = make_study(
    benchmark="miniwob",  # 可替换为 "webarena", "workarena_l1" 等
    agent_args=[AGENT_4o_MINI],
    comment="My first study",
)

# 运行实验，n_jobs 控制并行任务数
study.run(n_jobs=5)

断点续跑：如果实验中断或出现错误，可加载已有研究目录继续运行：

from agentlab.experiments.study import Study

study = Study.load("/path/to/your/study/dir")
study.find_incomplete(include_errors=True)
study.run()

模式三：分析结果

实验完成后，可以使用内置工具查看结果。

命令行可视化分析 (AgentXray)： 启动 Gradio 界面查看详细的执行轨迹、截图和动作日志。

agentlab-xray

操作流程：在界面中依次选择 Experiment -> Agent -> Task -> Seed，即可看到智能体的完整执行过程。点击截图可定位到具体步骤。

代码加载数据： 也可以通过 Python 直接将结果加载为 DataFrame 进行分析：

from agentlab.analyze import inspect_results

# 加载所有实验的摘要数据
result_df = inspect_results.load_result_df("path/to/your/study")

# 加载单个实验的详细对象
import browsergym.experiments as bgym
exp_result = bgym.ExpResult(result_df["exp_dir"][0])

# 访问具体数据，例如第一步的截图和动作
step_0_screenshot = exp_result.screenshots[0]
step_0_action = exp_result.steps_info[0].action