使用说明

agent-browser

The first text-first browser built for AI agents

Quick Start • Why • Integration • Tools • Architecture

English | Русский

问题

如今，每个AI浏览器工具的工作方式都是一样的：截图，将像素发送到LLM，希望它能找出要点击的内容。这在视觉噪音上浪费了数千个令牌，速度很慢，在动态页面上会中断。

代理浏览器 采取了一种根本不同的方法。它以屏幕阅读器的方式读取页面——通过可访问性树——并返回一个带有自动发现操作的语义文本快照。没有截图。没有选择器。没有脚本。

是什么让它与众不同

	代理浏览器	剧作家MCP	浏览器使用	舞台手
主要输入	辅助功能树	辅助功能图	屏幕截图	屏幕截图+HTML
每页代币数	~200-300	~1,500-3,000	~4,800+	~2,000+
动作发现	自动分组语义动作	原始元素列表	无	AI推断
页面分类	内置启发式	无	无	没有
页面差异（仅限增量）	内置	无	无	没有
意图过滤	内置（7个意图）	无	无	没有
多步流	自动检测，一次执行	无	无	没有
内容提取	6个内置提取器	无	无	没有
语言	TypeScript	TypeScript	Python	TypeScript

令牌使用情况比较

站点	代理浏览器	剧作家MCP
新闻报道	约250个代币	约4800个代币
谷歌搜索	约180个代币	约3200个代币
登录页面	~150个令牌	~2100个令牌

平均减少17倍 在上下文窗口使用中。

主要特点

语义动作发现

代理浏览器将元素分为有意义的类别，而不是简单的元素列表：

=== ACTIONS ===
[LOGIN FORM]
  fill(@e1) — Email input
  fill(@e2) — Password input
  click(@e3) — Sign in button

[SOCIAL SIGN-IN]
  click(@e4) — Continue with Google
  click(@e5) — Continue with Apple

[NAVIGATION]
  click(@e6) — Home
  click(@e7) — About
  click(@e8) — Pricing

预测性浏览引擎

四种功能在任何竞争工具中都找不到：

页面差异 --在第一个快照之后，只获取更改的内容。代币数量减少约80-90%。
意图过滤 --告诉浏览器你的目标（登录、搜索、购买）。只获取相关元素。
行动流程 --自动检测多步骤工作流（登录、搜索、结账）。只需一次呼叫即可执行。
智能提取 --提取文章、链接、标题、图像、表格、元数据，而无需编写选择器。

快速开始

先决条件

Node.js 18+
本地安装的Google Chrome或Chromium

安装

git clone https://github.com/malovnik/agent-browser.git
cd agent-browser
npm install
npm run build

连接到您的AI工具

看整合下面是您的特定工具。

整合

代理浏览器作为主控程序服务器通过stdio。任何兼容MCP的客户端都可以连接到它。

克劳德桌面版

编辑配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "agent-browser": {
      "command": "node",
      "args": ["/absolute/path/to/agent-browser/dist/bin/cli.js"]
    }
  }
}

默认情况下以头部模式运行（最佳防检测）。添加 "--headless" 对于无头模式，为args。

保存后重新启动Claude Desktop。21个工具将出现在工具选择器（锤子图标）中。

克劳德代码

claude mcp add --scope user agent-browser -- node /path/to/agent-browser/dist/bin/cli.js

对于无头模式：

claude mcp add --scope user agent-browser -- node /path/to/agent-browser/dist/bin/cli.js --headless

OpenClaw（ClawBot）

添加到您的 openclaw.json:

{
  "mcpServers": {
    "agent-browser": {
      "command": "node",
      "args": ["/absolute/path/to/agent-browser/dist/bin/cli.js"],
      "transport": "stdio"
    }
  }
}

或者通过CLI：

openclaw config set mcpServers.agent-browser.command "node"
openclaw config set mcpServers.agent-browser.args '["/absolute/path/to/agent-browser/dist/bin/cli.js"]'

光标

创建或编辑 ~/.cursor/mcp.json （全球）或 .cursor/mcp.json （项目范围）：

{
  "mcpServers": {
    "agent-browser": {
      "command": "node",
      "args": ["/absolute/path/to/agent-browser/dist/bin/cli.js"]
    }
  }
}

或者通过光标设置>工具和MCP>新建MCP服务器进行添加。

VS代码副本（1.99+）

创建 .vscode/mcp.json 在您的项目中：

{
  "servers": {
    "agent-browser": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/agent-browser/dist/bin/cli.js"]
    }
  }
}

Cline（VS代码）

单击临床窗格>配置>“配置MCP服务器”中的MCP服务器图标，然后添加：

{
  "mcpServers": {
    "agent-browser": {
      "command": "node",
      "args": ["/absolute/path/to/agent-browser/dist/bin/cli.js"],
      "disabled": false
    }
  }
}

帆板运动

编辑 ~/.codeium/windsurf/mcp_config.json 或通过级联面板中的MCP图标>配置打开它：

{
  "mcpServers": {
    "agent-browser": {
      "command": "node",
      "args": ["/absolute/path/to/agent-browser/dist/bin/cli.js"]
    }
  }
}

Continue.dev

在中创建JSON配置文件 .continue/mcpServers/agent-browser.json 在您的工作空间中：

{
  "mcpServers": {
    "agent-browser": {
      "command": "node",
      "args": ["/absolute/path/to/agent-browser/dist/bin/cli.js"]
    }
  }
}

Continue自动从以下位置获取JSON配置 .continue/mcpServers/ 目录。MCP工具在代理模式下可用。

任何MCP客户端

代理浏览器通过stdio使用模型上下文协议.启动服务器：

node dist/bin/cli.js

将您的客户端连接到此进程的stdin/stdout。

程序化使用（Node.js/TypeScript）

import { AgentBrowser } from "./src/index.js";

const browser = new AgentBrowser({ headless: true });
await browser.launch();

// Navigate and get semantic snapshot
const snapshot = await browser.navigate("https://example.com");
console.log(snapshot);

// Extract article text
const article = await browser.extract("article_text");
console.log(article.data);

// Execute a discovered flow
const flows = await browser.getFlows();
const result = await browser.executeFlow("login", {
  email: "user@example.com",
  password: "secret",
});

await browser.close();

CLI标志

标志	描述
`--headless`	运行时不显示浏览器窗口（默认：指向反检测）
`--chrome-path=PATH`	Chrome/Chromium可执行文件的路径
`--user-data-dir=PATH`	Chrome用户数据目录（持久会话/Cookie）
`--help`	显示帮助消息

工具参考

核心（15个工具）

工具	说明
`navigate`	转到URL，返回包含已发现操作的语义快照
`snapshot`	通过操作发现获取当前页面状态
`snapshot_compact`	最小令牌快照
`click`	按ref单击元素（例如。 `@e1`)
`fill`	按ref在输入字段中键入文本
`select`	按ref选择下拉选项
`scroll`	向上或向下滚动页面
`evaluate`	在浏览器中执行JavaScript
`screenshot`	拍摄视觉截图（谨慎使用）
`back`	返回历史记录
`forward`	在历史中向前导航
`tabs`	列出所有打开的选项卡
`new_tab`	打开新选项卡
`switch_tab`	按ID切换到选项卡
`close_tab`	按ID关闭选项卡
`close_browser`	关闭浏览器

预测性浏览引擎（6个工具）

工具	说明
`snapshot_intent`	按意图筛选的快照： `login`, `search`, `read_content`, `fill_form`, `navigate`, `buy`, `extract_data`
`diff`	仅获取自上次快照以来的更改（需要基线）
`extract`	提取内容： `article_text`, `links`, `headings`, `images`, `table_data`, `metadata`
`get_flows`	在当前页面上发现可用的多步骤工作流
`execute_flow`	使用参数执行流（例如。 `{email: "...", password: "..."}`)

建筑

src/
  bin/cli.ts               CLI entry point, parses flags, starts MCP server
  browser/engine.ts        CDP connection via puppeteer-core, tab management
  intelligence/
    analyzer.ts            Accessibility tree -> PageElement[]
    classifier.ts          Heuristic page type detection (10 types)
    actions.ts             Semantic action group discovery
    differ.ts              Page state diff engine (delta snapshots)
    intent.ts              Intent-aware element filtering (7 intents)
    flows.ts               Multi-step workflow auto-detection
    extractor.ts           Smart content extraction (6 targets)
  renderer/text.ts         PageState -> token-optimized text
  mcp/server.ts            MCP server with 21 tools
  index.ts                 AgentBrowser main class (public API)
  types.ts                 TypeScript interfaces

运作原理

1. Chrome (CDP)
      |
2. Accessibility Tree (via CDP Accessibility.getFullAXTree)
      |
3. DomAnalyzer -> PageElement[] (structured, typed elements)
      |
4. PageClassifier -> PageType (login, search, article, ...)
      |
5. ActionDiscoverer -> ActionGroup[] (LOGIN FORM, SEARCH, NAVIGATION, ...)
      |
6. TextRenderer -> Optimized text for LLM (~200-300 tokens)

为什么选择TypeScript（不是Rust/Go）

我们评估了Rust和Go中的重写。结论： 没有实质性的性能提升.

95%以上的执行时间 是CDP I/O（到Chrome的网络往返）。这是I/O限制，而不是CPU限制。TypeScript处理I/O和Rust或Go一样好。
木偶核心 是任何语言中最成熟的CDP客户端库。Rust替代品（氢氧化铬）和Go替代品（chromedp）不太成熟，生态系统较小。
MCP-SDK 是TypeScript原生的。重写需要维护协议绑定。
智能层（分类器、分析器、差异）占执行时间的<5%。
TypeScript实现了更快的迭代、更容易的贡献以及与MCP生态系统的更好兼容性。

贡献

看贡献.md 作为指导方针。

许可证

麻省理工学院