Browser-Agent

GUI 自动化编排器 — 让 AI 通过纯视觉理解操作任何界面

---

快速开始

pip install gui-agent-vlm
playwright install chromium

使用

from browser_agent import BrowserAgent

# 自动检测可用模型（Mano-P > Ollama > vLLM > LM Studio）
agent = BrowserAgent()
result = agent.run("搜索今天深圳的天气并告诉我结果")
print(result.text)

或通过 CLI：

browser-agent "搜索今天深圳的天气"

每一步模型输出结构化反射信息：

<reflection>
evaluation_previous_goal: "SUCCESS: 成功点击搜索按钮，页面切换到搜索结果"
memory: "搜索了深圳天气，结果页面有温湿度数据"
next_goal: "提取温度27°C和湿度46%信息，调用finish返回"
</reflection>

多标签页

agent = BrowserAgent()
agent.run("打开百度搜Python，然后在新标签页打开GitHub")

模型自动使用 open_tab / switch_tab / list_tabs 管理多页面。

指定模型

browser-agent --model-type ollama --model qwen3-vl:2b "搜索深圳天气"
browser-agent --model-type openai --model gpt-4o --api-key sk-xxx "搜索深圳天气"
browser-agent --model-type manop "搜索深圳天气"  # Mano-P 云端

架构

Agent (高层规划)
  │  "帮我查天气、整理文件、发邮件"
  ▼
browser-agent (编排器 + ModelRouter 自动选模型)
  │  Observe → Think → Act → Verify
  │
  ├── PlaywrightExecutor (浏览器)
  │   └── 通过 VLM 截图理解 + 操作
  │
  └── ManoPExecutor (桌面 GUI)
      └── 纯视觉定位（Mano-P 云端 API）

• 执行器可插拔 — Playwright（Web）/ Mano-P（桌面 GUI）
• 模型自动检测 — Mano-P → Ollama → vLLM → LM Studio 自动回退
• 三种调用方式 — CLI / Python API / MCP Server
• 多标签页 — 创建、切换、关闭标签页，独立维护 POI 状态
• DOM 脱水 — 结合 VLM 截图 + DOM 文本树的双通道观察
• 结构化反射 — 每步强制反思 + 步数警告 + 自动兜底

新特性

v0.2.0 — 推理框架 + 多标签页 + 自动兜底

推理与完成规则 — System Prompt 拆分为 <reasoning_rules> 和 <task_completion_rules>，模型先读 DOM 树再找截图、判断页面变化、卡住时自动调整策略。拿到结果立即 finish，不再空转。

多标签页支持 — 新增 4 个工具：open_tab / switch_tab / close_tab / list_tabs，每个标签页独立维护交互元素状态（POI）。适用于多页面穿梭任务。

自动兜底 — 模型连续 3 次无法返回有效动作时自动 finish 带最近思考内容。wait 工具支持自定义秒数（1-10s）。

v0.1.1 — DOM 脱水 + 结构化反射 + 智能提示

DOM 脱水（DOM Dehydration） — 模型不再只依赖截图"看图猜元素"。<dehydrated_dom> 以缩进文本树的形式列出页面上所有交互元素及其编号、层级关系。新出现的元素标记 *[N]，帮助模型感知页面变化。

结构化反射（Structured Reflection） — 每步模型必须输出 evaluation_previous_goal / memory / next_goal 三个字段，强制反思上一步结果、记录关键记忆、明确下一步目标。8B 模型效果显著——"百度搜索深圳天气"从 6 步缩到 3 步完成。

智能提示 — 剩余 ≤5 步时注入收尾警告，累计等待 ≥5 秒注入等待警告。防止模型无限制空转。

autoFixer JSON 容错 — 6 层 JSON 解析容错，自动补齐基本类型参数（如 "5" → {"mark_id": 5}）。

跨平台支持

browser-agent 是纯 Python 项目，依赖全部跨平台，支持 Linux、Windows、macOS。

平台兼容性矩阵

场景	Linux 原生	WSL2	Windows 原生	macOS
Playwright headless	✅	✅	✅	✅
Playwright headed	✅ Xvfb/X11	✅ WSLg(Win11)/Xvfb(Win10)	✅	✅
Ollama 本地 VLM	✅	✅	✅	✅
vLLM GPU	✅ 最优	⚠️ GPU 穿透复杂	⚠️ CUDA	⚠️ Metal
LM Studio	❌	❌	✅	✅
Mano-P 桌面 GUI	❌	❌	❌	✅ MLX

WSL2 中使用（Hermes Agent 典型场景）

Hermes Agent 运行在 WSL2 中时，browser-agent 可直接装在 WSL2 内使用：

# WSL2 中安装
pip install gui-agent-vlm playwright
playwright install chromium
playwright install-deps chromium   # 安装 Linux 系统依赖

# 使用（headless 模式，无需显示环境）
browser-agent "搜索今天深圳的天气"

headless 模式完全不需要显示环境，Playwright 在 WSL2 中运行无任何障碍。

如需查看浏览器窗口（调试用）：

• Windows 11: WSLg 自动支持，--no-headless 即可
• Windows 10: 需安装 X 服务器（如 VcXsrv），设置 DISPLAY=:0

跨平台调用（WSL2 Hermes → Windows browser-agent）

如果需要在 WSL2 中调用 Windows 原生桌面上的浏览器或 Mano-P：

# 方案 1: 全部在 WSL2 内完成（推荐）
# browser-agent 在 WSL2 中启动自己的 Chromium 进程，无需操作 Windows 浏览器
browser-agent "搜索深圳天气"

# 方案 2: 通过 MCP 桥接 Windows
# Windows 上启动 MCP Server
# PowerShell: browser-agent-mcp
# WSL2 中的 Hermes 通过 host.docker.internal:PORT 连接

关键理解: Playwright 启动的是自己管理的 Chromium 实例，不是操作"系统上已经打开的浏览器"。因此 WSL2 里的 browser-agent 无需与 Windows 端的浏览器交互——它自己在 WSL2 中启动 Chromium 即可。

模型选择

browser-agent 内置 ModelRouter，自动检测可用 VLM：

优先级	模型源	如何启用
P0	用户显式指定	--model-type / --model 参数
P1	Ollama	运行 ollama serve + 拉取 VLM 模型
P2	vLLM	vllm serve Qwen/Qwen2.5-VL-* --port 8000
P3	LM Studio	启动并加载 VLM 模型
P4	Agent 注入	设置 BROWSER_AGENT_FALLBACK_* 环境变量

Mano-P 云端 API 也已集成，代码就绪，但需要明略科技提供的 API key（MANOP_API_KEY），目前暂未开放注册。有 key 后可作为显式指定使用：--model-type manop。

任何 AI Agent 可以通过环境变量将自己的模型注入 browser-agent：

export BROWSER_AGENT_FALLBACK_MODEL_TYPE=openai
export BROWSER_AGENT_FALLBACK_MODEL=gpt-4o
export BROWSER_AGENT_FALLBACK_API_KEY=sk-xxx

MCP Server

browser-agent 内置 MCP Server，可被任何 MCP 兼容客户端调用：

{
  "mcpServers": {
    "browser-agent": {
      "command": "python",
      "args": ["-m", "browser_agent.mcp_server"]
    }
  }
}

支持工具：browser_navigate / browser_screenshot / browser_click / browser_type / browser_extract

作为 Agent Skill 使用

参阅 SKILL.md — 支持 CLI、Python API、MCP Server 三种集成方式。

Mano-P 集成

Mano-P 是明略科技开源的 GUI-VLA 模型，代码已集成，但暂未默认启用。

场景	方案	状态
Web 浏览器	PlaywrightExecutor + 本地 VLM	✅ 生产可用
桌面软件/3D/专业工具	ManoPExecutor + Mano-P Cloud API	⚠️ 代码就绪，需 MANOP_API_KEY（暂未开放注册）
Mano-P 本地推理	直接在本地运行模型	⏳ 仅 macOS Apple Silicon，等待 NVIDIA CUDA 开源

注意：Mano-P 不在自动检测队列中。持有了 MANOP_API_KEY 后通过 --model-type manop 显式指定即可使用。

测试

pytest tests/ -v

许可证

MIT