agent-browser

Overview

What is agent-browser?

agent-browser 是一個為 AI agents 與以 shell 為主的工作流程所設計的命令列瀏覽器自動化工具。它透過 Chrome DevTools Protocol (CDP) 直接連線到 Chrome 或 Chromium，讓你可以從終端機或 agent runtime 腳本化真實瀏覽器操作。

使用 agent-browser，你可以：

• 開啟並導覽網頁 (agent-browser open <url>)
• 透過結構化 snapshots 探索互動元件
• 點擊按鈕、追蹤連結並與表單互動
• 填寫輸入欄位、輸入文字與模擬按鍵
• 取得 snapshots 以了解頁面結構與可執行操作
• 管理 sessions 並保留登入狀態
• 走完驗證流程（包含 OAuth 與需要人工協助的 2FA）
• 使用 proxy 進行區域測試或在企業網路環境下操作
• 錄製效能 traces 進行 profiling
• 錄製瀏覽器操作影片，用於除錯或文件製作

Who is agent-browser for?

如果你符合以下情況，agent-browser 會是很合適的工具：

• 你正在執行需要實際瀏覽器控制的 AI agent 或自動化框架
• 你想用 CLI-first 的方式自動化 Chrome/Chromium 流程
• 你需要對 LLM 友善、可靠的元素定位（使用精簡的 @refs）
• 你要自動化登入流程、表單送出或多步驟 Web App 操作
• 你想將可重現的測試、示範或除錯過程輸出成影片或 traces

特別適用於以下情境：

• Browser automation：腳本化導覽、點擊和表單填寫
• Workflow automation：例如「登入 → 導覽 → 匯出報表」等端到端流程
• Test automation：Web App 的 smoke tests、回歸測試與效能 profiling

When agent-browser is and is not a good fit

在以下情況適合使用 agent-browser：

• 你可以在本機執行 CLI，且能安裝並使用 Chrome 或 Chromium
• 你需要可被 AI agent 控制的、可腳本化且具決定性的瀏覽器行為
• 你需要對 sessions、cookies 與驗證流程有細緻的掌控

在以下情況可能不適合：

• 無法在主機安裝或執行 Chrome/Chromium
• 你只需要取得原始 HTML 或簡單的 HTTP 請求（純 HTTP client 或 scraper 可能更簡單）
• 你需要在特定語言或 runtime 內以 headless 瀏覽器進行控制，且已高度綁定其他瀏覽器自動化函式庫

How to Use

Installation options

agent-browser 支援多種安裝方式，可依據你的環境選擇：

• npm (Node.js)

  npm i -g agent-browser
  

• Homebrew (macOS/Linux)

  brew install agent-browser
  

• Rust / Cargo

  cargo install agent-browser
  

安裝 CLI 之後，執行內建的 Chrome 設定流程：

agent-browser install

這會下載並設定相容的 Chrome/Chromium 版本。當有新版本時，可使用：

agent-browser upgrade

如果你在某個 agent 平台中將 agent-browser 當作 skill 使用，也可以這樣加入：

npx skills add https://github.com/vercel-labs/agent-browser --skill agent-browser

請查看 repository 中的 SKILL.md 以取得最新的 skill wiring 詳細說明。

Core browser automation workflow

每個 agent-browser 工作流程都遵循一個簡單迴圈：open → snapshot → interact → re-snapshot。

1. Navigate to a page

   agent-browser open https://example.com/form
   

2. Take a snapshot to discover elements
   使用互動式 snapshot 模式，取得附帶 @refs 的精簡可點擊與可填寫元素清單：

   agent-browser snapshot -i
   

   範例輸出（簡化版）：

   @e1 [input type="email"]
   @e2 [input type="password"]
   @e3 [button] "Submit"
   

3. Interact using refs

   agent-browser fill @e1 "user@example.com"
   agent-browser fill @e2 "password123"
   agent-browser click @e3
   

4. Wait and re-snapshot

   agent-browser wait --load networkidle
   agent-browser snapshot -i
   

這種模式讓 AI agent 能針對精簡的結構視圖進行推理，而不必處理完整 DOM，能大幅降低 context/token 使用量。

Command reference basics

agent-browser 提供一組相當完整的指令集合（請參考 references/commands.md），包含：

• Navigation

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

• Snapshot and refs

  agent-browser snapshot          # full tree
  agent-browser snapshot -i       # 僅列出互動式元素（建議使用）
  agent-browser snapshot -c       # 精簡輸出
  agent-browser snapshot -d 3     # 限制 depth
  agent-browser snapshot -s "#main"  # 限定在特定 CSS selector 範圍
  

• Interactions

  agent-browser click @e1
  agent-browser dblclick @e1
  agent-browser hover @e1
  agent-browser focus @e1
  agent-browser fill @e2 "text"
  agent-browser type @e2 "text"
  agent-browser press Enter
  

如需深入了解 @refs 的產生方式與有效期限，請參考 references/snapshot-refs.md。

Working with sessions and authentication

agent-browser 內建針對登入及多 session 瀏覽的工具，適合用來處理登入流程、多帳號測試或不同角色隔離情境。

• Named sessions（參考 references/session-management.md）：

  # Session "auth": login flow
  agent-browser --session auth open https://app.example.com/login
  
  # Session "public": separate browsing
  agent-browser --session public open https://example.com
  

  每個 session 都有獨立的 cookies、storage、cache 與 history。

• Session state persistence：

  # 儲存 cookies 與 storage
  agent-browser state save ./auth-state.json
  
  # 日後載入
  agent-browser state load ./auth-state.json
  agent-browser open https://app.example.com/dashboard
  

• Authentication patterns（參考 references/authentication.md）：

  • 從已登入、啟用除錯模式的 Chrome 匯入 cookies
  • 搭配 snapshots 與 fill/click 走完標準登入表單
  • 處理以 cookies 為基礎的驗證、HTTP basic auth，以及 token refresh

對於較複雜的 OAuth 或 2FA 流程，初始設定時仍可能需要人工參與，之後 agent-browser 便可重複使用已儲存的登入狀態。

Proxy support and network configuration

如果你需要透過 proxy 傳送流量（例如區域測試、流量限制或企業網路），可依 references/proxy-support.md 中的說明配置：

• 透過 CLI flag 設定 HTTP/HTTPS proxy

  agent-browser --proxy "http://proxy.example.com:8080" open https://example.com
  

• 使用環境變數設定

  export HTTP_PROXY="http://proxy.example.com:8080"
  export HTTPS_PROXY="https://proxy.example.com:8080"
  agent-browser open https://example.com
  

• SOCKS proxy

  export ALL_PROXY="socks5://proxy.example.com:1080"
  agent-browser open https://example.com
  

Profiling and performance tracing

在測試自動化與效能分析情境下，agent-browser 可以擷取 Chrome 的效能 traces（詳見 references/profiling.md）：

# Start profiling
agent-browser profiler start

# Run your scenario
agent-browser open https://example.com
agent-browser click @e1
agent-browser wait 1000

# Stop and save trace
agent-browser profiler stop ./trace.json

你可以在 Chrome DevTools（Performance 分頁）或其他相容工具中開啟 trace.json，分析 JavaScript 執行、渲染與 user timing events。

Video recording for debugging and documentation

agent-browser 能錄製瀏覽器操作過程的影片，對於除錯失敗的自動化流程或製作教學文件特別實用（參考 references/video-recording.md）：

# Start recording
agent-browser record start ./demo.webm

# Perform actions
agent-browser open https://example.com
agent-browser snapshot -i
agent-browser click @e1

# Stop recording
agent-browser record stop

你可以將這些 .webm 錄影嵌入文件、分享給團隊成員，或附在 bug reports 中。

Using templates for common workflows

repository 中的 templates/ 目錄提供多個 shell script 範本，協助你建立可重複使用的工作流程：

• templates/form-automation.sh – 用於結構化地填寫與送出表單
• templates/authenticated-session.sh – 示範登入並持久化 session state
• templates/capture-workflow.sh – 用於擷取多步驟流程的 snapshots 或錄影

你可以依自身環境、CI jobs 或 agent pipelines 需求，複製並調整這些 scripts。

FAQ

What problems does agent-browser solve compared to simple HTTP clients?

agent-browser 透過 CDP 控制真實的 Chrome/Chromium instance，意味著它可以處理：

• Client-side rendering 與複雜的 JavaScript
• 依賴瀏覽器 APIs 的 single-page apps
• 像真實使用者一樣的互動，例如點擊、輸入文字與按鍵操作
• 視覺呈現時機、渲染行為與效能 traces

如果你只需要從基本 endpoint 取得原始 HTML 或 JSON，一個 HTTP client 可能就足夠。但只要需求接近「像使用者一樣操作瀏覽器」，agent-browser 會更適合。

How do I install Chrome or Chromium for agent-browser?

使用 npm、Homebrew 或 Cargo 安裝 CLI 後，執行：

agent-browser install

這會下載並設定一個與 agent-browser 相容的 Chrome/Chromium 版本，透過 CDP 進行控制。未來有新版本時，可執行：

agent-browser upgrade

Can agent-browser reuse my existing logged-in browser session?

可以。references/authentication.md 說明了如何使用 --remote-debugging-port 啟動 Chrome，並從已登入的 session 匯入 cookies。匯入後，你可以使用 agent-browser state save 儲存該登入狀態，之後再載入即可，無需每次重走完整登入流程。

Is agent-browser suitable for CI and automated testing?

可以。只要 CI 環境中的 Chrome/Chromium 可用，agent-browser 這種 CLI 工具就非常適合用在自動化情境中。你可以：

• 在測試套件中跑端到端流程
• 在 build 過程中擷取效能 traces
• 錄製失敗情境的影片

在 CI 上，只要選擇與 build image 相符的安裝方式（npm、Homebrew 或 Cargo），再透過 shell scripts 或你的 agent framework 腳本化流程即可。

How does agent-browser help AI agents work with complex pages?

agent-browser 不會直接輸出完整 DOM，而是提供帶有穩定 @refs 的精簡 snapshots，用來描述關鍵元素（連結、按鈕、輸入欄位等）。這可以大幅降低 token 用量，並讓 AI agent 更容易：

• 理解頁面結構
• 透過 ref 選出正確元素
• 發出精準的 click、fill 與 press 指令

references/snapshot-refs.md 進一步說明 refs 的產生方式、何時需要重新整理，以及建立穩健自動化的最佳實務。

Does agent-browser support proxies and corporate networks?

支援。你可以透過 CLI flags（--proxy）或環境變數（HTTP_PROXY、HTTPS_PROXY、ALL_PROXY）設定 HTTP、HTTPS 與 SOCKS proxies。references/proxy-support.md 會介紹基本設定方式、需要驗證的 proxies、bypass 規則與常見問題排除。

Where should I start in the repository to learn more?

如果想更深入了解 agent-browser，可以從以下檔案開始：

• 先看 SKILL.md，掌握整體概念與快速上手步驟
• 再看 references/commands.md，了解完整指令與選項
• 依需求閱讀 references/authentication.md、references/session-management.md、references/snapshot-refs.md、references/profiling.md 與 references/video-recording.md 等主題文件
• 最後瀏覽 templates/ 目錄，參考可直接套用並調整的 workflow scripts，對應到你自己的使用情境