Agent Browser

代理浏览器

一个真正的、可见的AI代理光标浏览器。 真正的铬。真正的类人物理学。真实的审计追踪。代理以人类的方式驱动它：拖动、单击、键入、滚动——同时记录、回放和验证每个动作。

与每个主要的法学硕士合作：拟人克劳德、OpenAI GPT、谷歌双子座、Groq、Together、Fireworks、DeepInfra、Mistral、Cohere、xAI Grok、OpenRouter、困惑、Ollama（本地）、Ollama-Cloud（托管）、vLLM、LM Studio、llama.cpp或任何与OpenAI兼容的软件。 零锁定。

┌──────────────────────────────────────────────────────────────────┐
│                          Agent (your code)                       │
│   "submit the payment form"  ──┐                                 │
└────────────────────────────────┼─────────────────────────────────┘
                                 │  HTTP POST /sessions/:id/plan
                                 ▼
┌──────────────────────────────────────────────────────────────────┐
│                      AgentBrowser runtime                        │
│  Planner  ──▶  findAndClick (DOM ▶ vision-LLM)  ──▶  cursor      │
│     │              │                                  │          │
│     │              ▼                                  ▼          │
│     │     verifier (DOM diff)               Bezier trajectory    │
│     │              │                          + CDP raw events   │
│     ▼              ▼                                  │          │
│  action      action.completed event ──▶  recorder (JSONL)        │
│  memory                                              │           │
│  (skip LLM                                           ▼           │
│   on visit                                  WebSocket / SSE      │
│   #2+)                                       to operator UI      │
└──────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
                     Real visible cursor moves on real Chromium

______________________________________________________________________

为什么存在

每一个现有的浏览器自动化工具都是首先为人类构建的，并为代理进行了改装。他们讲DOM操作。它们生成8000个标记HTML转储。他们每次跑步都会重新学习每个网站。他们没有审计追踪。他们被每一个cookie横幅屏蔽了。

AgentBrowser反转了这一点。 光标是真实可见的。所有输入都经过CDP原始鼠标事件。API用目标说话，而不是用选择器说话。失败的操作会自动恢复。每一个动作都会得到验证。该系统永久学习每个网站，并在各个领域共享知识。

Other tools                       │   AgentBrowser
─────────────────────────────────│──────────────────────────────────
8000 tokens of HTML              │   50 tokens of structured meaning
agent guesses #submit-btn-v2     │   { goal: "submit the form" }
no replay, no audit              │   JSONL trace, deterministic replay
re-learns every visit            │   action memory, 7x faster on visit 3
blocked by every cookie wall     │   auto-dismiss + force-removal
no captcha story                 │   2Captcha / hCaptcha / Turnstile
no fingerprint defenses          │   per-context WebGL/canvas/audio noise
single integration: library      │   library + MCP + HTTP + WS + SSE + replay
locked to one LLM vendor         │   17 providers, one env var swap (Claude/GPT/
                                 │   Gemini/Ollama/vLLM/Groq/Together/Fireworks/...)

______________________________________________________________________

五分钟演示

git clone https://github.com/AshtonVaughan/agentbrowser
cd agentbrowser
npm install && npx playwright install chromium && npm run build

# Pick ANY LLM provider:
ANTHROPIC_API_KEY=sk-ant-...   npm run http   # Claude (default)
# or
OPENAI_API_KEY=sk-...          npm run http   # GPT
# or
GOOGLE_API_KEY=...             npm run http   # Gemini
# or
GROQ_API_KEY=gsk_...           npm run http   # Groq (Llama on LPUs)
# or run fully local with Ollama:
ollama serve &
AGENTBROWSER_LLM_PROVIDER=ollama OLLAMA_MODEL=llama3.2-vision npm run http
# or use Ollama Cloud:
OLLAMA_CLOUD_API_KEY=... npm run http

在另一个终端中：

# Create a session
curl -X POST localhost:3100/api/v1/sessions
# → { "session_id": "abc123..." }

# Plan + execute a goal end-to-end
curl -X POST localhost:3100/api/v1/sessions/abc123/plan \
  -H 'content-type: application/json' \
  -d '{"goal":"go to news.ycombinator.com and click the top story"}'
# → { success: true, steps: [...], duration_ms: 4200 }

# Watch it live
open ui/operator/index.html

代理的光标在屏幕上以人工方式移动。每个cursor.move、click、page change都会实时流式传输到操作员UI。每一个动作都被记录下来 ~/.agentbrowser/traces/ 用于重播。

______________________________________________________________________

你得到了什么

可见的类人光标

• 通过上下文初始化脚本注入SVG光标精灵
• 贝塞尔曲线轨迹具有抖动、易于进出、可选过冲
• 所有输入均通过CDP Input.dispatchMouseEvent （非剧作家定位器）
• 点击涟漪动画，淡化14点光标轨迹
• 用于重放再现性的每条轨迹确定性种子

混合动作层

愿景管道

• extractElementBoxes(page) 返回丰富元素目录：id/role/tag/可访问名称/值/bbox/选择器/禁用
• bboxScreenshot(sessionId) 返回一个视口PNG，其中在每个交互式目标+元素列表上绘制了带有编号的青色框
• VisionLLM.decide(goal, screenshot, elements) 发送给克劳德·索内特，解析 {element_id, action, rationale}
• cursor.clickByBox(bbox) 用可见光标点击视觉导出的坐标

自我修复

• 动作验证器 快照每次操作前的ElementBoxes，结算后的diffs，在URL更改/添加/删除/textChanged/移动元素时声明verified=true
• 陈旧元素回收 在 cursor.clickBySelector 回落到 getByText(originalText) 选择器故障
• 模态断续器 在视口中心检测固定/绝对高z索引对话框，将其分类为阻止程序（cookie/同意/订阅关键字）或用户相关程序（登录对话框），自动关闭阻止程序并重试
• 选择器库仅从验证结果中学习 -除非点击确实改变了页面，否则内存中没有条目

站点+动作记忆

• SQLite WAL用于并发读取。每个域选择器库+页面模型缓存。
• ActionMemory -SHA-1页面签名×目标哈希→ 选择器×成功/失败计数器。访问第2个已知页面不需要LLM调用。
• 跨域转移: recallByGoal(goal, excludeDomain) 返回来自其他域的同一逻辑目标的获胜选择器。系统学习了“提交付款”→ stripe.com上的“#pay-btn”按钮；它在paddle.com上尝试了与假设相同的选择器。
• decay(unusedSinceMs) 将过时的条目计数减半，这样图书馆在网站发生变化时也能保持健康。

录音+回放

• 每个操作都以JSONL格式流式传输到 ~/.agentbrowser/traces/.jsonl
• ReplayEngine 读取跟踪，以可配置的速度将事件分派到新会话
• compactTrace() 折叠60个事件cursor。将轨迹移动到1，合并连续的cursor类型事件，丢弃微等待
• 计划审核 在每个步骤边界捕获屏幕截图+元素列表-合规级回放图元

技能库

• “技能”是一个带有命名槽令牌的记录痕迹($email, $password)
• SkillLibrary.parameterize(events, slots) 用标记替换文字值（最长优先，以避免部分匹配错误）
• 通过JSON文件保存/加载/列出/删除 ~/.agentbrowser/skills/
• 便携.skill.json包 使用magic+version+元数据（作者、许可证、标签）的格式-将技能与代理代码捆绑在一起或发布到注册表；用户导入+绑定自己的凭据

验证码

• TwoCaptchaSolver 通过2Captcha API为hCaptcha+reCAPTCHA v2+Cloudflare旋转闸门
• 页面侧 DETECT_CAPTCHA_SCRIPT 查找所有三种类型的站点密钥
• solveCaptchaIfPresent(page, solver) 链：检测→ 解决→ 注入令牌→ 火灾变化/输入事件→ 调用数据回调
• 可插拔过孔 CaptchaSolver 界面（插入AntiCaptcha、CapMonster等）

防指纹

• applyFingerprintShield(context) 按上下文初始化脚本
• 恶搞WebGL UNMASKED_VENDOR/RENDELER（5个GPU配置文件）、navigator.hardwareConcurrency、navigator.deviceMemory、AudioContext（1e-7噪声）、画布到数据URL（~0.08%像素抖动）、navigater.plugins
• 根据上下文确定的种子指纹在会话内保持稳定，但在会话之间有所不同

多标签

• engine.newTab(sessionId, url?) 在同一上下文中打开一个选项卡（共享cookie/auth）
• 每个选项卡都有自己的 HumanCursor. switchTab / closeTab / listTabs.
• HTTP:GET/POST/DELETE /sessions/:id/tabs，POST /tabs/:tab/switch

通用LLM提供商支持（零锁定）

• 17家供应商有线 -通过设置一个环境变量来交换它们中的任何一个
• LLMProvider 接口(complete() + completeWithImage())分析器+视觉LLM+规划器都使用这种抽象，从不使用SDK
• 启动时的自动检测从环境变量中选择正确的提供程序

// Pick a provider explicitly (any of the 17):
import { AgentBrowserHttpServer, presets } from 'agentbrowser';

const server = new AgentBrowserHttpServer({
  llm_provider: presets.ollamaCloud(),   // or .openai() or .groq() etc
  // ...
});

或者只是设置 AGENTBROWSER_LLM_PROVIDER=ollama 服务器自动连线。用以下内容覆盖模型 _MODEL=.

Chrome扩展程序（使用Cookie驱动Chrome）

• 安装 extensions/chrome/ 在开发模式下(chrome://extensions → 装载未包装）
• 单击代理浏览器图标，粘贴服务器URL+API键，单击连接
• 现在有个特工在打电话 POST /api/v1/agents//cmd 使用您的Cookie和登录状态驱动您的Chrome
• 清单v3+ chrome.debugger 用于真实的CDP鼠标事件+ chrome.scripting 视觉/提取
• 看 extensions/chrome/README.md 对于完整的安全模型

操作员+记录器+内存+技能UI

• ui/operator/index.html -实时截图+光标轨迹叠加+事件时间线+快速操作面板
• ui/recorder/index.html -实时WebSocket事件流+多通道时间线画布+回放洗涤器+JSONL导出
• ui/memory/index.html -按域分页的动作内存浏览器+衰减控制+JSON导出
• docs/pricing.html -4层定价页面已连接到 /api/v1/billing/checkout 用于自助支付Stripe
• docs/skills.html -技能市场登陆8项精选技能（登录条纹、登录谷歌、亚马逊添加到购物车、github创建问题等）
• 所有这些都是单文件香草HTML/CSS/JS。无构建步骤。

转录助手（“观看”视频的代理）

• findCaptionTracks(page) 检测HTML5 ` 油管 playerCaptionsTracklistRenderer` +自定义播放器标记
• parseVTT(text) / parseJSON3(json) 将标准字幕格式转换为键入格式 TranscriptSegment[]
• transcribeFromCaptions(page) 一枪：检测→ 获取→ parse
• transcriptToText(segments) 连接以供LLM使用

生产运行时间

• Fastify上的HTTP REST API+WebSocket+SSE，带有承载令牌身份验证+每密钥速率限制
• 30多个端点，OpenAPI 3.1规范 /api/v1/openapi.json
• 条纹计费有线（结账+webhook+签名验证+许可证发放）
• 普罗米修斯 /metrics +准备状态探测+仪表板摘要端点
• 4层许可证脚手架（免费/专业/团队/企业），带功能门和配额跟踪
• 多级Dockerfile，docker用持久卷+1GB shm_size为Chromium编写
• Python+TypeScript SDK客户端

______________________________________________________________________

建筑

┌─────────────────────────────────────────────────────────────────┐
│  Operator UI  (browser-based dashboard)                         │
│   - live screenshot stream         - cursor trail viz           │
│   - action log + reasoning         - manual takeover            │
│  Recorder UI                                                    │
│   - timeline scrubber              - replay export              │
└─────────────────────────────────────────────────────────────────┘
                          ▲
                          │  WebSocket events + SSE frames + REST
┌─────────────────────────┴───────────────────────────────────────┐
│                   AgentBrowser HTTP Control Plane               │
│  ┌──────────────────┐  ┌──────────────────┐  ┌────────────────┐ │
│  │  REST + WS + SSE │  │  Bearer auth +   │  │  License +     │ │
│  │  Fastify         │  │  per-key rate    │  │  quota system  │ │
│  └──────────────────┘  └──────────────────┘  └────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                          ▲
                          │
┌─────────────────────────┴───────────────────────────────────────┐
│                    AgentBrowser Core Runtime                    │
│  ┌──────────────────┐  ┌──────────────────┐  ┌────────────────┐ │
│  │  Planner         │  │  findAndClick    │  │  Recorder +    │ │
│  │  (goal → steps)  │  │  hybrid action   │  │  Replay engine │ │
│  └──────────────────┘  └──────────────────┘  └────────────────┘ │
│  ┌──────────────────┐  ┌──────────────────┐  ┌────────────────┐ │
│  │  Verifier        │  │  Modal           │  │  Action memory │ │
│  │  (diff snapshots)│  │  interrupter     │  │  (skip LLM)    │ │
│  └──────────────────┘  └──────────────────┘  └────────────────┘ │
│  ┌──────────────────┐  ┌──────────────────┐  ┌────────────────┐ │
│  │  Vision pipeline │  │  HumanCursor     │  │  Site memory   │ │
│  │  bbox + annotate │  │  Bezier + CDP    │  │  WAL SQLite    │ │
│  │  + VisionLLM     │  │  trail + ripple  │  │  + selectors   │ │
│  └──────────────────┘  └──────────────────┘  └────────────────┘ │
│  ┌──────────────────┐  ┌──────────────────┐  ┌────────────────┐ │
│  │  Anti-fingerprint│  │  Captcha solver  │  │  LLM provider  │ │
│  │  (canvas/WebGL)  │  │  + auto-inject   │  │  (Anthropic /  │ │
│  │                  │  │                  │  │   OpenAI / etc)│ │
│  └──────────────────┘  └──────────────────┘  └────────────────┘ │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  Browser Engine - Playwright + stealth + multi-tab     │    │
│  │  ↓                                                      │    │
│  │  Chromium (the real browser, with the visible cursor)  │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

______________________________________________________________________

快速入门-4种方法

作为TypeScript库

import { AgentBrowser } from 'agentbrowser';

const browser = new AgentBrowser({
  anthropic_api_key: process.env.ANTHROPIC_API_KEY,
  headless: false,    // watch the cursor move
  stealth: true,
});
await browser.launch();

const state = await browser.navigate('https://news.ycombinator.com');
console.log(state.page_type);          // 'listing'
console.log(state.available_actions);  // [{ name: 'navigate_to_new', ... }, ...]

await browser.action('navigate_to_new');

const data = await browser.extract({
  top_story: 'title of the top story',
  points: 'upvote count',
  author: 'submitter username',
});

await browser.close();

通过HTTP

curl -X POST http://localhost:3100/api/v1/sessions
curl -X POST http://localhost:3100/api/v1/sessions/$ID/navigate -d '{"url":"https://example.com"}'
curl -X POST http://localhost:3100/api/v1/sessions/$ID/find_and_click -d '{"goal":"submit the form"}'
curl http://localhost:3100/api/v1/sessions/$ID/screenshot/bbox

开发包

from agentbrowser import AgentBrowserClient

client = AgentBrowserClient("http://localhost:3100", api_key="...")
with client.create_session() as s:
    s.navigate("https://example.com")
    s.click(selector="a")
    png, elements = s.annotated_screenshot()

MCP服务器（克劳德代码等）

添加 ~/.claude.json:

{
  "mcpServers": {
    "agentbrowser": {
      "command": "node",
      "args": ["/path/to/agentbrowser/dist/server/mcp.js"],
      "env": { "ANTHROPIC_API_KEY": "sk-..." }
    }
  }
}

______________________________________________________________________

存储库结构

src/
├── engine/             Browser lifecycle, sessions, tabs
│   ├── browser.ts      Playwright wrapper, cursor wiring, popup handling
│   └── tabs.ts         Multi-tab manager
├── input/              Cursor + physics + fingerprint shield
│   ├── cursor.ts       HumanCursor: SVG overlay, CDP input, click/drag/type
│   ├── trajectory.ts   Bezier path generator with jitter + overshoot
│   └── fingerprint.ts  WebGL/canvas/audio anti-fingerprint patches
├── vision/             Vision pipeline
│   ├── bbox.ts         Element catalog extraction
│   ├── annotate.ts     Numbered-box screenshot annotator
│   ├── diff.ts         Snapshot diff (added/removed/moved/textChanged)
│   └── llm.ts          Claude vision integration
├── runtime/            Action execution + autonomy
│   ├── executor.ts     Action runner with action-memory hot path
│   ├── find.ts         Hybrid DOM-then-vision findAndClick
│   ├── verifier.ts     Action verification via snapshot diff
│   ├── modal-interrupter.ts  Cookie/consent/popup detection
│   ├── planner.ts      LLM goal decomposition + multi-step execution
│   ├── plan-audit.ts   Per-step screenshot + element capture
│   ├── recorder.ts     JSONL action stream
│   ├── replay.ts       Deterministic trace replay
│   ├── compactor.ts    Trace compaction (collapse cursor.move runs)
│   ├── events.ts       In-process event broker (pub/sub)
│   ├── captcha.ts      2Captcha API integration
│   └── captcha-solver.ts  Detect → solve → inject pipeline
├── memory/             Persistent storage
│   ├── store.ts        Site memory (page model cache + selector library)
│   └── action-memory.ts  Per-(page,goal) selector cache + cross-domain transfer
├── llm/                Provider abstraction
│   ├── provider.ts     LLMProvider interface
│   ├── anthropic.ts    Anthropic SDK wrapper
│   ├── openai.ts       OpenAI-compatible (works with vLLM/Ollama too)
│   └── index.ts        autoDetectProvider
├── semantic/           Page analysis
│   └── analyzer.ts     Page-to-SemanticPageModel via LLM
├── skills/             Skill library
│   ├── skills.ts       Parameterize/save/load/run
│   └── package.ts      .skill.json export/import format
├── server/             Production server surfaces
│   ├── http.ts         Fastify + REST + WS + SSE + auth + rate limit
│   ├── openapi.ts      OpenAPI 3.1 spec
│   ├── license.ts      Tier system + quota tracking
│   └── mcp.ts          MCP server for Claude Code et al.
├── bin/
│   └── http.ts         HTTP server entry point
├── util/
│   └── coords.ts       Viewport ↔ document ↔ screenshot coord conversions
├── types.ts            Shared types (SemanticPageModel, ActionDefinition, ...)
└── index.ts            Public API barrel

tests/                  Vitest suite (119 tests, 21 files)
clients/
├── python/             Python SDK (zero deps, stdlib urllib)
└── typescript/         TypeScript SDK (browser + Node compatible)
ui/
├── operator/           Live dashboard (single HTML file)
└── recorder/           Real-time trace timeline (single HTML file)
docs/                   Public docs site (single HTML file)
examples/               Working agent demos
.agentbrowser-meta/     Internal build planning + iteration log
Dockerfile              Multi-stage slim image (~700MB with Chromium)
docker-compose.yml      Local stack with persistent volume

______________________________________________________________________

API表面

22个HTTP端点，当配置API密钥时，所有承载器都经过身份验证。完整的OpenAPI 3.1 /api/v1/openapi.json.

______________________________________________________________________

生产部署

码头工人

docker compose up -d
# AgentBrowser on http://localhost:3100
# Memory + traces persist in named volume

认证+速率限制

AGENTBROWSER_API_KEYS=key1,key2 \
ANTHROPIC_API_KEY=sk-ant-... \
node dist/bin/http.js

速率限制默认为600 req/min/key。覆盖 AGENTBROWSER_RATE_LIMIT_PER_MINUTE.

可观测性

• 每个动作都会发出一个类型 SessionEvent 到进程内代理
• WebSocket客户端在以下位置订阅 /api/v1/sessions/:id/events （有200个事件回放缓冲区用于重新连接）
• JSONL跟踪位于 ~/.agentbrowser/traces/ 是审核日志吗
• compactTrace() 保持长轨迹小而不失保真度

______________________________________________________________________

测试地点：

______________________________________________________________________

许可证

MIT。鼓励商业使用。

有关收购或合伙企业的询问： ashtonluca@gmail.com.