agent-in-browser

agent-in-browser

适用于任何 AI Agent、任何模型和任何测试运行器的真实浏览器——一个零依赖的二进制文件。

_{这是真实录制，并非模拟演示。Agent 将页面读取为带有元素引用的快照，输入文字、填写表单并点击，先在 Chrome（CDP）中操作，再在 Firefox（WebDriver BiDi）中操作。使用 task demo 重新生成。}

agent-in-browser 是对「Claude in Chrome」的一种开放实现。它不需要扩展程序或特定厂商的运行时。它通过浏览器原生的自动化协议驱动你已有的浏览器：

浏览器	协议	状态
Chrome、Chrome Beta/Canary、Chromium、Edge、Brave、Vivaldi、Opera	Chrome DevTools Protocol (CDP)	✅
Firefox、Firefox Developer Edition / Nightly	WebDriver BiDi	✅
Safari	WebDriver (safaridriver)	🛣 已检测，路线图

它有三种使用方式，均基于同一工具目录：

1. MCP 服务（agent-in-browser mcp）：可接入 Claude Code、Claude Desktop、Cursor、Codex、Gemini CLI、Windsurf、VS Code/Copilot、Zed、opencode 以及任何其他 MCP 客户端，不受其使用的模型限制。
2. Shell CLI（agent-in-browser call <tool> …）：适用于不支持 MCP 的 Agent、脚本和用户。所有调用共享一个持久的浏览器。
3. 场景运行器（agent-in-browser run test.yaml --browser chrome,firefox）：将工具调用作为自动化测试在多个浏览器上重放，并生成 JUnit/JSON 报告。

二进制文件内置了一个 Agent 技能（skills/agent-in-browser/SKILL.md），用于向 Agent 介绍工作流。

安装

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/Gwakko/agent-in-browser/main/scripts/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/Gwakko/agent-in-browser/main/scripts/install.ps1 | iex

# Homebrew (macOS / Linux)
brew install gwakko/tap/agent-in-browser

# With Go
go install github.com/gwakko/agent-in-browser/cmd/agent-in-browser@latest

# From a checkout (needs Task: https://taskfile.dev)
task install            # → ~/.local/bin/agent-in-browser + alias `aib`

连接你的 Agent

agent-in-browser setup claude-code --write    # runs `claude mcp add --scope user …`
agent-in-browser setup cursor --write         # merges ~/.cursor/mcp.json (a .bak is kept)
agent-in-browser setup codex --write          # appends to ~/.codex/config.toml
agent-in-browser setup gemini --write         # ~/.gemini/settings.json
agent-in-browser setup vscode                 # prints the snippet for .vscode/mcp.json
agent-in-browser skill install --for claude   # ~/.claude/skills/agent-in-browser (also: codex, agents, --dir)

**Claude Desktop，一键安装：**从最新版本下载 agent-in-browser-<version>.mcpb 并打开。它也已列入 MCP Registry，名称为 io.github.Gwakko/agent-in-browser。

不加 --write 时，setup 只会打印配置。使用 --args "--browser firefox --headless" 传递浏览器选项。所有客户端的说明请参阅 docs/integrations.md。

在 Shell 中使用

agent-in-browser call navigate url=localhost:3000
agent-in-browser call snapshot
#   - textbox "Email" [ref=e3] (required, type=email)
#   - button "Sign up" [ref=e7]
agent-in-browser call type ref=e3 [email protected]
agent-in-browser call click ref=e7
agent-in-browser call wait_for text=Welcome
agent-in-browser call console_messages level=error
agent-in-browser call screenshot            # → prints PNG path
agent-in-browser stop

可用标志（可在命令行的任何位置使用）：--browser firefox、--headless、用于启动第二个独立浏览器的 --instance work、用于连接到你自行启动的浏览器的 --endpoint http://127.0.0.1:9222，以及 --viewport 390x844。

测试场景

name: signup
browsers: [chrome, firefox]
steps:
  - navigate: http://localhost:3000/signup
  - fill_form:
      fields:
        - { selector: "#email", value: "[email protected]" }
        - { match: "I accept the terms", value: true }
  - click: Sign up
  - wait_for: { text: "Welcome" }
  - assert: { url_contains: "/dashboard", no_console_errors: true }

agent-in-browser run tests/*.yaml --browser chrome,firefox,edge --junit report.xml

完整格式请参阅：skills/agent-in-browser/references/scenarios.md。

工具

browser_status · browsers_installed · tabs_list · tab_new · tab_select · tab_close · navigate · snapshot · find · click · hover · type · press_key · fill_form · scroll · wait_for · get_text · screenshot · evaluate · console_messages · network_requests · resize · browser_close

参数说明见 docs/tools.md，该文件由 task docs:tools 生成。

工作原理

 agent ──MCP/stdio──┐
 shell ──call───────┼──▶ tools ──▶ session ──▶ Driver ──CDP──────▶ Chrome / Edge / Brave / …
 CI ────run yaml────┘     (one catalogue)  (attach|launch)  └─BiDi─────▶ Firefox
                                                            page lib (injected JS):
                                                            snapshot · refs · fill · find

• 浏览器运行在专用配置文件（~/.agent-in-browser/profiles/<instance>-<browser>）中，并且是分离运行的，因此 MCP 服务重启后它仍会继续运行。通过 ~/.agent-in-browser/instances/<name>.json，单独的 CLI 调用会复用该浏览器。
• 页面理解（快照、引用、表单填写）通过注入的 JavaScript实现，在所有引擎中的工作方式都相同。可信输入、屏幕截图、标签页以及控制台/网络捕获则由各协议的驱动程序提供。
• 详情：docs/architecture.md · 浏览器说明：docs/browsers.md · 计划：docs/roadmap.md。

开发

task build      # bin/agent-in-browser
task test       # unit tests
task test:e2e   # scenario on every installed browser
task smoke      # CLI scenario run, chrome+firefox
task inspect    # MCP Inspector against the local build
task build:all  # cross-compile 6 targets into dist/
task release TAG=v0.1.0   # tag → GitHub Actions → goreleaser

安全说明

• 调试端点仅监听 127.0.0.1。即便如此，任何本地进程都能控制该浏览器，因此不要在其中登录你不愿交给 Agent 使用的账户。
• 从 Chrome 136 开始，Chrome 会拒绝对默认 Chrome 配置文件进行远程调试。agent-in-browser 始终使用自己的配置文件。若要复用登录信息，只需在 Agent 的浏览器窗口中登录一次，配置文件便会保留这些信息。

许可证：MIT