跳转到主要内容
browseruse-bench 通过 BaseAgent 接口集成 Agent。框架负责任务加载、CLI 解析、工作目录和结果保存，你只需实现 run_task() 并注册即可。

​
现有三个agent的接入

​
1. browser-use — Python SDK 直接调用

接口：直接 import browser_use Python 包，在进程内异步运行。 任务 → BrowserUseAgent.run_task() → 创建 LLM 实例（OpenAI/Gemini/Anthropic 等） → open_browser_session() 打开浏览器会话 → browser_use.Agent(task, llm, browser).run() → 解析 history，返回 AgentResult 优点：最深度集成，能拿到 token 用量、每步截图、完整 action history。

​
2. Skyvern — Python SDK + 本地嵌入式服务

接口：import skyvern，需要本地 PostgreSQL 做认证，支持本地和云端两种模式。 任务 → SkyvernAgent.prepare()（初始化 DB 认证） → SkyvernAgent.run_task() → Skyvern.local() 或 Skyvern(api_key=...) → skyvern.run_task(prompt, engine, ...) → 轮询 run_id 等待完成 → 从 artifacts 目录收集截图，返回 AgentResult 特点：依赖最重（需要 PostgreSQL），但可以用自己的 LLM 替换 Skyvern 云端模型。

​
3. Agent-TARS — subprocess CLI

接口：调用 agent-tars run --input "..." ... 命令行工具，完全黑盒。 任务 → AgentTARSAgent.run_task() → 拼接 CLI 参数 → subprocess.Popen(["agent-tars", "run", ...]) → 等待进程结束（带 timeout） → 解析 event-stream.jsonl 提取 actions/metrics → 返回 AgentResult 优点：最轻量，不需要了解 agent 内部实现，只需要有可执行的 CLI。

​
新 agent 需要开放什么 / 怎么接入

​
Agent必须开放的接口（三选一）

方式要求
Python SDK可 pip install 的包，有 run(task) 类 API，能拿到结果
HTTP APIREST 接口，可提交任务 + 轮询结果
CLI可执行命令，接受 task 作为参数，退出后输出结果文件

​
必须实现的输出（AgentResult）

AgentResult(
    task_id=...,
    env_status="success" | "failed",   # 环境是否正常
    agent_done="done" | "timeout" | "error" | "max_steps",
    answer="...",          # agent 给出的最终答案（评估时使用）
    action_history=[...],  # 操作步骤列表
    screenshots=[...],     # 轨迹截图文件名列表
    metrics=AgentMetrics(
        end_to_end_ms=...,
        steps=...,
    ),
)

​
需要创建的文件

browseruse_bench/agents/<agent_module>.py   # BaseAgent 子类
browseruse_bench/agents/__init__.py         # 添加 import
config.yaml                                # 根配置注册（推荐）
configs/agent_registry.yaml                # 注册 venv、entrypoint、supported_benchmarks
pyproject.toml                             # 可选：新增 optional dependency

​
支持的两种接入方式

​
一、Code Agent 接入

你不需要手动实现，只需要告诉Code Agent我需要接入某个Agent，参考当前的某一种Agent的接入方式

​
以 接入Claude Code作为浏览器Agent 为例

我想参考Agent-TARS的接入方式接入claude-code作为我的评测框架的一个浏览器Agent，约束条件如下：
  • 参考Agent-TARS 的 subprocess CLI方式接入
  • 请先给出我前置安装条件，等我安装完整之后再进行代码实现
  • 增加相关的配置，注意使用根目录下的配置文件config.yaml，以及agent的环境变量注册配置configs/agent_registry.yaml
  • 输出目录下必须有result.json，记录Agent的结果，trajectory放置过程截图，api_logs放置中间的过程
  • 其他约束条件:
  • 逐行输出 JSON 事件，type=result 包含最终答案，type=user 包含工具结果（含截图 base64）
  • 限制 Agent 只能使用 Playwright 浏览器工具，以免使用搜索类API完成
  • 非交互模式下跳过权限确认弹窗
  • 接入完成之后给我一个运行实例
以下是code agent的输出：（注意不是全部，只是部分输出的摘取） 前置条件： 
# 1. 安装 Claude Code CLI
npm install -g @anthropic-ai/claude-code

# 2. 登录认证
claude auth login

# 3. 在 user scope 添加 Playwright MCP（确保子进程能找到）
claude mcp add playwright --scope user -- npx @playwright/mcp@latest
代码变动 新增了 browseruse_bench/agents/claude_code.py 更改了 browseruse_bench/agents/init.py 在 config.yaml 中完成了注册： 
agents:
  my-code-agent:
    active_model: default
    models:
      default:
        model_id: your-model-id   # 注意是 model_id，不是 model
        api_key: $YOUR_API_KEY
    defaults:
      max_turns: 50
      timeout: 300
      allowed_tools: "mcp__playwright*"
运行脚本 
bubench run \
  --agent claude-code \
  --benchmark LexBench-Browser \
  --mode first_n \
  --count 1

​
二、手动接入

适用于自研 Agent、Python SDK 或 HTTP API 类 Agent，需要自己实现浏览器控制逻辑。

​
手动接入步骤

​
第一步：实现 Agent

# browseruse_bench/agents/my_agent.py
from __future__ import annotations

import logging
from pathlib import Path
from typing import Any, Dict

from browseruse_bench.agents.base import BaseAgent
from browseruse_bench.agents.registry import register_agent
from browseruse_bench.schemas import AgentMetrics, AgentResult

logger = logging.getLogger(__name__)


@register_agent
class MyAgent(BaseAgent):
    name = "my-agent"

    def run_task(
        self,
        task_info: Dict[str, Any],
        agent_config: Dict[str, Any],
        task_workspace: Path,
    ) -> AgentResult:
        task_id = task_info.get("task_id", "unknown")
        task_text = task_info.get("task_text", "")

        # ... agent 逻辑 ...

        return AgentResult(
            task_id=task_id,
            env_status="success",
            agent_done="done",
            answer="Final answer here",
            action_history=[],
            metrics=AgentMetrics(end_to_end_ms=0, steps=0),
        )

​
第二步：确保模块被导入

注册发生在模块被导入时。请在 browseruse_bench/agents/__init__.py 添加： 
from browseruse_bench.agents import my_agent  # noqa: F401

​
第三步：在 config.yaml 中注册

在根目录 config.yaml 的 agents 下添加模型配置： 
agents:
  my-agent:
    active_model: default
    models:
      default:
        model_id: gpt-4.1
        api_key: $OPENAI_API_KEY
    defaults:
      timeout: 300
      max_steps: 50
同时在 configs/agent_registry.yaml 中注册元数据： 
my-agent:
  path: browseruse_bench/agents
  entrypoint: browseruse_bench/runner/agent_runner.py
  venv: .venv
  supported_benchmarks:
    - Online-Mind2Web
    - LexBench-Browser

​
第四步：快速运行测试

bubench run \
  --agent my-agent \
  --benchmark Online-Mind2Web \
  --mode first_n \
  --count 1

​
参考字段说明

​
task_info 包含什么？

框架从 benchmark 数据集加载的任务字典，标准字段：
  • task_id（字符串）
  • task_text（字符串）
  • url（字符串）
  • prompt（字符串，可选）

​
agent_config 包含什么？

默认从根目录 config.yaml 的 agents.<agent>.models[active_model] 读取（可通过 --agent-config 显式指定外部文件）。框架会注入 timeout_seconds。

​
task_workspace 是什么？

框架为每个任务创建的输出目录：<output_dir>/tasks/<task_id>/。 截图、日志等中间产物保存在此；框架在同目录写入 result.json。

​
浏览器后端约束

如果你的 Agent 需要浏览器能力（手动接入模式），请遵循统一后端契约： 
from browseruse_bench.browsers import open_browser_session

browser_id = agent_config.get("browser_id") or "Chrome-Local"
with open_browser_session(browser_id=browser_id, agent_name=self.name, agent_config=agent_config) as ctx:
    # 用 ctx.cdp_url 或 ctx.transport 构建浏览器实例
    ...
Provider 生命周期代码（创建/销毁会话）放在 browseruse_bench/browsers/providers/，cleanup 失败应记录日志并容忍，不应覆盖任务执行阶段的原始错误。