Agent Browser

Agent Browser

一款基于 Rust 的高速无头浏览器自动化命令行工具，支持回退到 Node.js，可让 AI Agent 通过结构化命令浏览、点击、输入并截取页面快照。

安装

推荐使用 npm

npm install -g agent-browser
agent-browser install
agent-browser install --with-deps

从源代码安装

git clone https://github.com/vercel-labs/agent-browser
cd agent-browser
pnpm install
pnpm build
agent-browser install

快速入门

agent-browser open example.com
agent-browser snapshot
agent-browser click @e2
agent-browser fill @e3 "[email protected]"
agent-browser get text @e1
agent-browser screenshot page.png
agent-browser close

使用真实 Chrome 配置文件（用于 OAuth／已登录会话）

对于需要 Google／Discord 等账号登录的网站（例如 star-swap.com）：

方法 1：使用自定义配置文件启动 Chrome，通过 CDP 连接

# Terminal 1: Launch Chrome with your real profile and remote debugging
google-chrome --remote-debugging-port=9222 --user-data-dir=/home/willr/.config/google-chrome/Default &

# Terminal 2: Connect agent-browser to that Chrome instance
agent-browser --cdp 9222 open "https://star-swap.com"
agent-browser --cdp 9222 snapshot -i
agent-browser --cdp 9222 click e2

# This reuses your existing Google session - no re-login needed!
# Works for: Google OAuth, Discord OAuth, any site you're logged into in Chrome

方法 2：持久化会话（首次手动登录）

# First time: headed mode, login manually
agent-browser --headed --session starswap open "https://star-swap.com"
# Complete Google OAuth manually in the browser window
# Close when done

# Future runs: cookies persist!
agent-browser --session starswap open "https://star-swap.com"
# Already logged in automatically

am.will.ryan Chrome 配置文件： /home/willr/.config/google-chrome/Default

核心命令

导航

agent-browser open <url>
agent-browser back
agent-browser forward
agent-browser reload

交互

agent-browser click <sel>
agent-browser dblclick <sel>
agent-browser focus <sel>
agent-browser type <sel> <text>
agent-browser fill <sel> <text>
agent-browser clear <sel>
agent-browser press <key>
agent-browser keydown <key>
agent-browser keyup <key>
agent-browser hover <sel>
agent-browser select <sel> <val>
agent-browser check <sel>
agent-browser uncheck <sel>
agent-browser drag <src> <tgt>
agent-browser upload <sel> <files>

提取与信息

agent-browser snapshot
agent-browser get text <sel>
agent-browser get html <sel>
agent-browser get value <sel>
agent-browser get attr <sel> <attr>
agent-browser get title
agent-browser get url
agent-browser get count <sel>
agent-browser get box <sel>
agent-browser screenshot [path]
agent-browser pdf <path>

检查状态

agent-browser is visible <sel>
agent-browser is enabled <sel>
agent-browser is checked <sel>

查找元素

• agent-browser find role [value]
• agent-browser find text
• agent-browser find label [value]
• agent-browser find placeholder [value]
• agent-browser find alt
• agent-browser find title
• agent-browser find testid [value]

操作包括 click、fill、check、hover 和 text。

等待与计时

agent-browser wait <selector>
agent-browser wait <ms>
agent-browser wait --text "Welcome"
agent-browser wait --url "**/dash"
agent-browser wait --load networkidle

高级控制

agent-browser scroll <dir> [px]
agent-browser scrollintoview <sel>
agent-browser eval <js>
agent-browser mouse move <x> <y>
agent-browser cookies
agent-browser storage local
agent-browser tab new [url]
agent-browser frame <sel>
agent-browser dialog accept [text]

会话

运行多个相互隔离的浏览器实例。

agent-browser --session agent1 open site-a.com
agent-browser --session agent2 open site-b.com

快照选项

snapshot 命令支持筛选，以减少输出大小。

• agent-browser snapshot -i
• agent-browser snapshot -c
• agent-browser snapshot -d 3
• agent-browser snapshot -s "#main"

选择器与引用

引用可在快照中确定性地选择元素。使用 @ref 语法。

agent-browser snapshot
agent-browser click @e2

Agent 模式

使用 --json 获取机器可读的输出。

agent-browser snapshot --json

最佳 AI 工作流

• 使用 agent-browser open 导航
• 使用 agent-browser snapshot -i --json 观察
• 使用快照中的 @ref 执行操作
• 使用 agent-browser snapshot 验证

故障排除

• 如果在 Linux ARM64 上找不到命令，请使用 bin 文件夹中的完整路径。
• 如果找不到元素，请使用 snapshot 查找正确的 ref。
• 如果页面尚未加载，请在导航后添加 wait 命令。
• 使用 --headed 显示浏览器窗口以进行调试。

选项

• --session 使用隔离会话。
• --json 提供 JSON 输出。
• --full 截取整页屏幕截图。
• --headed 显示浏览器窗口。
• --timeout 设置命令超时时间，单位为毫秒。

注意事项

• 每次页面加载后，Refs 都保持稳定，但导航后会改变。
• 导航后务必重新截取快照以获取新的 refs。
• 对输入字段使用 fill 而非 type，以确保清除已有文本。