AgentLab — 用于构建和评测网页智能体的研究平台

[](https://pypi.org/project/agentlab/) [](http://www.apache.org/licenses/LICENSE-2.0) [](https://pypistats.org/packages/agentlab) [](https://star-history.com/#ServiceNow/AgentLab) [](https://github.com/ServiceNow/AgentLab/actions/workflows/code_format.yml) [](https://github.com/ServiceNow/AgentLab/actions/workflows/unit_tests.yml) [🛠️ 安装](#%EF%B8%8F-setup-agentlab)  |  [🤖 助手](#-ui-assistant)  |  [🚀 启动实验](#-launch-experiments)  |  [🔍 分析结果](#-analyse-results)  | 
[🏆 排行榜](#-leaderboard)  |  [🤖 构建你的智能体](#-implement-a-new-agent)  |  [↻ 可复现性](#-reproducibility)  |  [💪 BrowserGym](https://github.com/ServiceNow/BrowserGym) [演示任务解决过程：](https://github.com/ServiceNow/BrowserGym/assets/26232819/e0bfc788-cc8e-44f1-b8c3-0d1114108b85)

[!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 key> # 如果使用 openai 模型

export OPENROUTER_API_KEY=<你的 openrouter api key> # 如果使用 openrouter 模型

export AZURE_OPENAI_API_KEY=<你的 azure api key> # 如果使用 azure 模型
export AZURE_OPENAI_ENDPOINT=<你的 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 以使用各种选项启动实验。这就像一个懒人 CLI，实际上更方便。只需注释或取消注释你需要的行，或按需修改（但不要推送到仓库）。

任务超时

复杂的网络环境、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 提交一个 PR。为了获得更流畅的并行体验，请考虑使用 WorkArena 等基准测试。

🔍 分析结果

加载结果

类 ExpResult 提供了一个懒加载器，用于加载特定实验的所有信息。你可以使用 yield_all_exp_results 递归查找目录中的所有结果。最后，load_result_df 将所有摘要信息收集到一个 DataFrame 中。有关示例用法，请参阅 inspect_results.ipynb。

from agentlab.analyze import inspect_results

# 将研究中所有实验的摘要加载到 DataFrame 中
result_df = inspect_results.load_result_df("path/to/your/study")

# 加载第一个实验的详细结果
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

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 中的大部分函数。

如果你认为你的智能体应该直接包含在 AgentLab 中，请告诉我们，它可以被添加到 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 LLMs。
- AZURE_OPENAI_API_KEY，默认用于 AzureOpenAI LLMs。
- 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 (int)，用于指定 ray 仪表板应访问的端口。

其他

如果你想更快地下载 HF 模型

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

📝 引用此工作

如果你想引用 AgentLab，请使用以下两个 bibtex 条目：

```tex
@article{
chezelles2025browsergym,
title={The BrowserGym Ecosystem