vercel-labs / agent-browser

agent-browser Browser automation for AI agents: open pages, read them as an accessibility tree, and act on elements from the shell. agent-browser is a native Rust CLI that gives an AI agent a browser it can drive one command at a time. snapshot returns the page as compact text with a ref such as @e1 for each element. The agent acts on a ref, reads the page again to check the result, and repeats. The browser stays open between commands, so each step is one short shell call.

agent-browser 是一个用于 AI 智能体的浏览器自动化工具：它能够打开网页，将其读取为辅助功能树（accessibility tree），并允许通过 shell 对页面元素进行操作。agent-browser 是一个原生的 Rust 命令行工具，为 AI 智能体提供了一个可以逐条指令驱动的浏览器。snapshot 命令会将页面以紧凑文本的形式返回，并为每个元素分配一个引用（如 @e1）。智能体通过引用进行操作，再次读取页面以检查结果，并重复此过程。浏览器在指令之间保持开启状态，因此每一步操作都只是一个简短的 shell 调用。

Install npm install -g agent-browser agent-browser install # download Chrome for Testing (first time only) Homebrew: brew install agent-browser, then agent-browser install. Linux: agent-browser install —with-deps also installs the browser’s system libraries. No install: npx agent-browser open example.com. Project installs, building from source, upgrade, and doctor are covered in Installation.

安装方式：使用 npm install -g agent-browser 进行安装，随后运行 agent-browser install（仅首次运行需下载 Chrome for Testing）。Homebrew 用户可使用 brew install agent-browser，然后运行 agent-browser install。Linux 用户使用 agent-browser install --with-deps 可同时安装浏览器所需的系统库。无需安装即可使用：npx agent-browser open example.com。关于项目安装、源码构建、升级及诊断工具的使用，请参考“安装”章节。

Quick start agent-browser open example.com agent-browser snapshot -i # interactive elements, each with a ref agent-browser click @e1 # act on a ref from that snapshot agent-browser get url # check the result agent-browser close The snapshot for example.com: - link “Learn more” [ref=e1] Refs describe the page at the time of the snapshot. After navigation or a DOM change, take a new snapshot before using refs again. CSS selectors, text, XPath, and semantic locators also work, for example agent-browser find role button click —name “Submit”. See Selectors. A click fails, instead of reporting success, when the target is hidden, disabled, outside the viewport, or covered by another element such as a consent banner. Dismiss the covering element, take a new snapshot, and retry. The full walkthrough is in the quick start.

快速入门：agent-browser open example.com，agent-browser snapshot -i（查看带有引用的交互元素），agent-browser click @e1（基于快照引用进行操作），agent-browser get url（检查结果），agent-browser close。example.com 的快照示例：- link "Learn more" [ref=e1]。引用仅描述快照时刻的页面状态。在导航或 DOM 发生变化后，请务必在再次使用引用前获取新快照。CSS 选择器、文本、XPath 和语义定位器同样适用，例如 agent-browser find role button click --name "Submit"（详见“选择器”章节）。如果目标元素被隐藏、禁用、位于视口外或被其他元素（如同意横幅）遮挡，点击操作将会失败，而不是报告成功。此时请先移除遮挡元素，获取新快照，然后重试。完整指南请参阅快速入门文档。

How it works The CLI sends each command to a background daemon that starts on the first command and controls the browser over the Chrome DevTools Protocol. Each —session gets its own daemon and browser. By default, the daemon closes a headless browser and exits after one hour without commands, saving state first when session persistence is configured. Chrome for Testing is the default browser. You can also attach to a running Chrome with —cdp or —auto-connect (CDP mode), select the Lightpanda or Obscura engine with —engine, drive Mobile Safari in the iOS Simulator, or use a cloud browser provider such as Browserbase, Browserless, Browser Use, Kernel, or AgentCore.

工作原理：CLI 将每条指令发送至后台守护进程，该进程在首次执行指令时启动，并通过 Chrome DevTools 协议控制浏览器。每个 --session 都会拥有独立的守护进程和浏览器实例。默认情况下，若一小时内无指令操作，守护进程将关闭无头浏览器并退出；若配置了会话持久化，则会先保存状态。Chrome for Testing 是默认浏览器。你也可以通过 --cdp 或 --auto-connect（CDP 模式）连接到正在运行的 Chrome，使用 --engine 选择 Lightpanda 或 Obscura 引擎，驱动 iOS 模拟器中的 Mobile Safari，或使用 Browserbase、Browserless、Browser Use、Kernel 或 AgentCore 等云浏览器提供商。

For AI agents The CLI ships skills that match its version: agent-browser skills get core # the core loop, refs, waiting, and common workflows agent-browser skills get core —ref commands # one reference, such as the full command list agent-browser skills get core —full # adds the full command reference and templates agent-browser skills list # specialized skills: electron, slack, dogfood, and more Install the discovery skill into an agent harness from skills.sh: npx skills add vercel-labs/agent-browser The installed skill is a thin stub that tells the agent to load agent-browser skills get core, so its instructions always match the installed CLI. Or add this to your AGENTS.md: Use agent-browser for browser automation. Before the first use, run agent-browser skills get core and follow it. For MCP clients, agent-browser mcp starts an MCP server over stdio. See MCP server.

面向 AI 智能体：CLI 提供了与其版本匹配的技能包：agent-browser skills get core（核心循环、引用、等待及常见工作流），agent-browser skills get core --ref commands（单一参考，如完整指令列表），agent-browser skills get core --full（包含完整指令参考和模板），agent-browser skills list（专业技能：electron、slack、dogfood 等）。可通过 skills.sh 将发现技能安装到智能体框架中：npx skills add vercel-labs/agent-browser。安装的技能是一个轻量级存根，指示智能体加载 agent-browser skills get core，确保其指令始终与已安装的 CLI 版本匹配。或者在 AGENTS.md 中添加：使用 agent-browser 进行浏览器自动化。首次使用前，请运行 agent-browser skills get core 并按提示操作。对于 MCP 客户端，agent-browser mcp 可通过 stdio 启动 MCP 服务器（详见 MCP 服务器章节）。

Commands Run agent-browser —help for the full list, or agent-browser —help for one command. Group Commands Docs Navigate and read open, back, forward, reload, read, snapshot, get, is Core, Snapshots Interact click, dblclick, fill, type, press, keyboard, hover, focus, select, check, uncheck, scroll, drag, upload, mouse, find Core, Find elements Wait wait Wait Capture screenshot, pdf, record, download, diff Recording, Diffing, Files Page and network state cookies, storage, network, set, clipboard, eval, pushstate Network, Settings Tabs, frames, and dialogs tab, frame, dialog Tabs and frames Debug and performance console, errors, highlight, inspect, trace, profiler, vitals, react, a11y Debugging, Profiler, React Sessions and auth session, state, auth, profiles, confirm, deny Sessions, Security Agents and integrations skills, mcp, webmcp, flow, chat, batch, plugin Skills, WebMCP, Plugins Observe stream, dashboard Streaming, Dashboard Setup install, upgrade, doctor, connect, close Installation Flags, environment variables, and agent-browser.json are documented in Configuration.

指令：运行 agent-browser --help 查看完整列表，或运行 agent-browser <command> --help 查看特定指令。指令分组包括：导航与读取（open, back, forward, reload, read, snapshot, get, is）、交互（click, dblclick, fill, type, press, keyboard, hover, focus, select, check, uncheck, scroll, drag, upload, mouse, find）、等待（wait）、捕获（screenshot, pdf, record, download, diff）、页面与网络状态（cookies, storage, network, set, clipboard, eval, pushstate）、标签页/框架/对话框（tab, frame, dialog）、调试与性能（console, errors, highlight, inspect, trace, profiler, vitals, react, a11y）、会话与认证（session, state, auth, profiles, confirm, deny）、智能体与集成（skills, mcp, webmcp, flow, chat, batch, plugin）、观察（stream, dashboard）以及设置（install, upgrade, doctor, connect, close）。标志、环境变量和 agent-browser.json 的详细说明请参考“配置”章节。

Platforms Native binaries ship for macOS (ARM64, x64), Linux (ARM64, x64, glibc and musl), and Windows (x64). The npm package picks the right binary for the host. Development Building from source requires Node.js 24 or later, pnpm 11 or later, and Rust: pnpm install pnpm build:source # builds the dashboard and the native CLI pnpm link —global agent-browser install Run the Rust checks from cli/: cargo fmt — —check cargo clippy cargo test cargo test e2e — —ignored —test-threads=1 # launches real headless Chrome AGENTS.md lists the files to update with each change, the docs checks, and the release process.

平台：提供 macOS (ARM64, x64)、Linux (ARM64, x64, glibc 和 musl) 以及 Windows (x64) 的原生二进制文件。npm 包会自动选择适合宿主机的二进制文件。开发：从源码构建需要 Node.js 24 或更高版本、pnpm 11 或更高版本以及 Rust。运行 pnpm install，pnpm build:source（构建仪表盘和原生 CLI），pnpm link --global，agent-browser install。在 cli/ 目录下运行 Rust 检查：cargo fmt -- --check，cargo clippy，cargo test，cargo test e2e -- --ignored --test-threads=1（启动真实的无头 Chrome）。AGENTS.md 列出了每次变更需要更新的文件、文档检查项以及发布流程。

Documentation agent-browser.dev: introduction, guides, and reference Commands and Configuration Security: the auth vault, domain allowlists, action policies, and content boundaries Next.js and Vercel and eve: running agent-browser in Vercel Sandbox and eve agents Changelog License Apache-2.0

文档：agent-browser.dev 包含介绍、指南、参考、指令与配置、安全性（认证库、域名白名单、操作策略和内容边界）、Next.js/Vercel/eve（在 Vercel Sandbox 和 eve 智能体中运行 agent-browser）、更新日志及 Apache-2.0 许可证。