agent-browser：專為 AI Agent 設計的瀏覽器自動化工具 開源工具

問題背景：傳統瀏覽器自動化對 AI 不友善

傳統的瀏覽器自動化工具（如 Playwright、Puppeteer）原本是為開發者設計的，使用 CSS 選擇器或 XPath 來定位網頁元素。然而當 AI Agent 需要操作網頁時，會面臨以下挑戰：

• Token 消耗過大：將完整的 DOM Tree 餵給 LLM 會導致 Token 爆炸，一個簡單的登入頁面可能就需要數千個 tokens
• 雜訊過多：網頁包含大量視覺裝飾、隱藏元素和冗餘結構，對 AI 來說都是無用的干擾
• 選擇器脆弱：CSS 類名經常變動（如 btn-login-xyz-123），導致 AI 生成的指令容易失效

Pulumi 團隊在實測中發現，使用 Playwright MCP 操作一個簡單的網頁需要消耗 15,000-20,000 tokens，而 agent-browser 只需要 2,000-3,000 tokens¹，這就是 82-93% 的 context 減少從何而來。

agent-browser 的解決方案：語義化 refs 系統

agent-browser 採用「快照 + 引用」(Snapshot + Refs) 的創新機制來解決這個問題：

1. 快照 (Snapshot)

將當前網頁轉換為簡化的抽象層，只保留 AI 需要的資訊：

agent-browser snapshot -i -c

輸出範例：

- link "首頁" [ref=e1]
- link "AI 知識庫" [ref=e2]
- button "聯絡我們" [ref=e3]
- textbox "搜尋..." [ref=e4]

2. 語義化引用 (Semantic Refs)

為頁面上的互動元素分配唯一的短 ID（如 @e1, @e2），AI 只需輸出簡單的指令：

agent-browser click @e2
agent-browser fill @e4 "agent-browser"
agent-browser press Enter

相比傳統方式需要寫 page.click('button.login-btn.css-xyz-123')，語義化 refs 更直觀且抗脆性更強。

3. 過濾雜訊

自動移除不影響互動的視覺裝飾、隱藏元素和冗餘結構，讓 AI 專注於實際可操作的元素。

核心功能與技術規格

基本操作流程

典型的 AI Agent 操作迴圈：

# 1. 導航到網頁
agent-browser open "https://example.com"

# 2. 獲取頁面結構與元素 ID（關鍵！）
agent-browser snapshot -i -c

# 3. 根據 ID 執行動作
agent-browser click @e1
agent-browser fill @e2 "username"

# 4. 頁面變更後重新 Snapshot
agent-browser snapshot -i -c

# 5. 關閉瀏覽器
agent-browser close

Trace 記錄與網路分析

專為除錯和數據抓取設計的進階功能：

完整 Trace 記錄

記錄操作過程、網路請求、console 日誌和截圖：

# 開始記錄
agent-browser trace start /tmp/trace.zip

# 執行操作
agent-browser open "https://example.com"
agent-browser click @e1

# 停止並儲存
agent-browser trace stop /tmp/trace.zip

# 解析網路資料
unzip -p /tmp/trace.zip trace.network | jq -s 'map(select(.type == "resource-snapshot"))'

# 視覺化查看（開啟 Playwright UI）
npx playwright show-trace /tmp/trace.zip

網路攔截與 Mock

# 查看網路請求
agent-browser network requests --filter api

# 攔截路由
agent-browser network route "**/api/data"

# Mock 回應
agent-browser network route "**/api/auth" --body '{"success":true}'

與主流工具對比

使用場景建議

• agent-browser：構建自主瀏覽網頁的 AI Agent，開箱即用
• Playwright：需要極致底層控制或複雜的 E2E 測試
• Chrome MCP：IDE（如 Cursor）與瀏覽器溝通的標準橋樑，需要完整 DevTools 功能

安裝與開始使用

安裝步驟

# 全域安裝 CLI
npm install -g agent-browser

# 安裝瀏覽器依賴 (Chromium)
agent-browser install

# Linux 可能需要額外依賴
# agent-browser install --with-deps

# 驗證安裝
agent-browser --version

快速測試範例

# 開啟網站
agent-browser open "https://www.oao.tw"

# 取得頁面結構
agent-browser snapshot -i -c

# 截圖
agent-browser screenshot /tmp/page.png

# 查看 console 日誌
agent-browser console

# 檢查錯誤
agent-browser errors

# 關閉瀏覽器
agent-browser close

實際測試案例：整合到 Claude Code

我們在 OAO Studio 網站進行了實測，使用 agent-browser 驗證網頁功能：

實際使用限制

Bot 防護挑戰

在測試抓取 Medium 文章時，我們遇到了 Cloudflare 防護的挑戰：

• 簡單 403 Forbidden：agent-browser 可以繞過（因為使用真實瀏覽器）
• Cloudflare Challenge / Turnstile：即使是 agent-browser 也會被偵測並攔截，顯示 "Verify you are human" 頁面

動態內容限制

對於高度依賴 Canvas 或極度複雜的 SPA 網站，Refs 系統可能無法捕捉所有互動細節。在這些情況下，傳統的 Playwright 可能仍是更好的選擇。

AI Agent 設計最佳實踐

1. Token 節省優先：始終使用 snapshot -i -c 獲取精簡資訊，避免將完整 HTML 餵給 LLM
2. 容錯機制：網頁載入是異步的。若操作失敗（元素未找到），應先執行 wait 或 reload 再重試
3. 無頭模式：在伺服器環境運行時，確保使用 Headless 模式並配置適當的 args（如 --no-sandbox）
4. Trace 記錄：在開發階段開啟 trace 記錄，便於除錯和分析 Agent 行為

總結與建議

agent-browser 是一個「AI 原生」的瀏覽器操作介面。它不追求 Playwright 的大而全，而是專注於「如何讓 LLM 以最少的 Token 代價理解並操作網頁」。

• AI Agent 開發者：這是目前最輕量且高效的選擇，開箱即用，82% Context 減少是實實在在的優勢
• QA 測試工程師：如果需要複雜的測試場景或底層控制，Playwright 仍是更好的選擇
• 數據抓取：適合抓取一般網站，但面對 Cloudflare 等嚴格防護時需要額外處理
• IDE 整合：如果需要在 IDE 中操作瀏覽器並存取完整 DevTools，Chrome MCP 更合適

隨著 AI Agent 技術的成熟，專為 AI 優化的工具鏈將成為主流。agent-browser 作為這個趨勢的先驅，已經證明了「AI 優先」設計理念的價值。如果你正在構建自主 Web Agent，不妨從 agent-browser 開始。