agent-browser：面向 AI Agent 的瀏覽器自動化

agent-browser 是一個為 AI Agent 設計的 Apache-2.0 瀏覽器自動化 CLI。它不要求 Agent 產生完整的 Playwright 程式，而是將導覽、互動、檢查、狀態、網路與可觀測性操作公開為 Shell 命令。持久化原生精靈會在這些命令之間保留瀏覽器。

此專案結合了三個概念：

精簡的無障礙樹快照為模型提供頁面的結構化檢視，而不必傳送完整 DOM。
快照參照用於在後續命令中識別元素。
長時間執行的精靈將瀏覽器生命週期與每個 CLI 程序的生命週期分離。

截至 2026 年 9 月 11 日，現行版本為 0.37.1。專案變更快速，因此本文中與版本相關的行為會連結到 0.37.1 原始碼修訂版。

瀏覽器自動化為何需要面向 Agent 的介面 #

Playwright 與類似函式庫提供精確的瀏覽器 API，但由 LLM 驅動的程序直接使用這些 API 時，會產生額外成本：

產生的原始碼會消耗上下文，並且需要執行環境。
原始 DOM 包含腳本、樣式、隱藏節點和框架產生的結構，而這些內容很少有助於下一個動作。
從一次觀察產生的 CSS 選擇器可能會在重新渲染後失效。
分離的腳本需要明確管理瀏覽器與上下文的生命週期。

agent-browser 改變的是介面，而不是瀏覽器。Agent 觀察精簡的樹、選擇一項操作、執行一個命令，然後再次觀察：

flowchart LR
    Goal[User Goal] --> Model[Agent]
    Model -->|open or snapshot| CLI[agent-browser CLI]
    CLI --> Daemon[Native Daemon]
    Daemon -->|CDP or WebDriver| Browser[Browser]
    Browser --> Daemon
    Daemon -->|Snapshot and Refs| Model
    Model -->|click @e2| CLI

模型仍然決定要執行什麼，而 CLI 提供穩定的動作詞彙並管理瀏覽器狀態。根據專案概覽，典型的文字快照約使用 200–400 個 Token，相比之下，完整 DOM 會使用 3,000–5,000 個 Token。這些數字是專案估計，而非獨立基準測試，但背後的原因很明確：無障礙樹省略了 Agent 不需要的大部分實作細節。

架構 #

每次呼叫都會啟動一個小型 CLI 用戶端。用戶端解析引數並與原生 Rust 精靈通訊，而精靈負責擁有或連接瀏覽器，並透過 Chrome DevTools Protocol（CDP）傳送命令。

flowchart TB
    subgraph Commands[Short-Lived Processes]
        C1[open]
        C2[snapshot]
        C3[click]
    end

    Socket[Local IPC]
    Daemon[Persistent Rust Daemon]
    CDP[Chrome DevTools Protocol]
    Chrome[Chrome or Chromium]

    C1 --> Socket
    C2 --> Socket
    C3 --> Socket
    Socket --> Daemon
    Daemon --> CDP
    CDP --> Chrome

持久性很重要，因為登入狀態、開啟的分頁、Cookie jar 和記憶體中的應用程式狀態會在 Shell 命令之間保留。精靈會自動啟動。預設情況下，它會儲存已設定的還原狀態、關閉本機擁有的無頭瀏覽器，並在一小時沒有命令或儀表板輸入後結束。有頭瀏覽器、Safari 和 iOS WebDriver 工作階段，以及透過 CDP 連接的瀏覽器不適用預設的關閉行為。可以透過 --idle-timeout 或 AGENT_BROWSER_IDLE_TIMEOUT_MS 設定逾時時間。

目前版本使用原生 Rust 實作；較早的 Node.js 和 Playwright 精靈已被移除。由於原生路徑直接使用 CDP，Chrome 和 Chromium 是主要目標。專案也提供：

相容於 CDP 的 Lightpanda 引擎，但不支援有頭模式、擴充功能或持久化設定檔；
透過 Appium 和 XCUITest 在 iOS Simulator 中使用 Safari；以及
供 Browser Use、Browserbase、Browserless、Kernel 和 AWS Bedrock AgentCore 使用的雲端瀏覽器提供者。

不同後端的能力並不完全相同。例如，帶註解的螢幕擷取可以在 CDP 路徑上運作，但不能在 Safari WebDriver 路徑上運作。

安裝與執行 agent-browser #

npm 套件會安裝平台專用的原生二進位檔：

npm install -g agent-browser
agent-browser install

agent-browser install 會尋找相容的現有瀏覽器，或下載 Chrome for Testing。Linux 主機也可以要求安裝瀏覽器系統相依套件：

agent-browser install --with-deps

其他支援的安裝方式包括 npx、專案本機 npm 相依套件、macOS 上的 Homebrew，以及 Cargo。已安裝的精靈不需要 Playwright。npm 發行版將 Node.js 24 宣告為需求，因為其啟動器會選擇原生二進位檔；而透過 Homebrew 安裝的二進位檔不需要 Node.js 精靈。建置此儲存庫時需要 pnpm 11 和 Rust。安裝指南也記載了 agent-browser doctor，該命令會檢查瀏覽器探索、設定、精靈檔案、提供者連線和暫存無頭啟動。

最小互動序列如下：

agent-browser open https://example.com
agent-browser snapshot -i
agent-browser click @e2
agent-browser screenshot page.png
agent-browser close

CLI 包含超過 50 個命令。相關命令群組包括導覽、表單、鍵盤與指標輸入、分頁、框架、檔案、Cookie、儲存空間、網路路由、HAR 擷取、螢幕擷取、PDF 產生、視訊錄製、效能分析與差異比較。agent-browser read <url> 可以在不啟動 Chrome 的情況下取得 Agent 可讀取的內容，而 agent-browser mcp 則透過 MCP stdio 伺服器公開命令介面。

快照與元素參照 #

snapshot 是核心抽象。它會序列化無障礙樹，並為元素指定參照：

text

@e1 [heading] "Documentation" [level=1]
@e2 [input type="search"] placeholder="Search"
@e3 [button] "Submit"

Agent 不必自行產生 CSS 選擇器即可操作：

agent-browser fill @e2 "session persistence"
agent-browser click @e3

多個篩選器可以減少上下文使用量：

選項	效果
`-i`、`--interactive`	僅包含互動元素
`-c`、`--compact`	移除空的結構元素
`-d`、`--depth`	限制樹深度
`-s`、`--selector`	將樹限制在 CSS 選擇器內
`-u`、`--urls`	包含連結目的地

參照屬於產生它們的頁面狀態。導覽和有意義的 DOM 變更會使參照失效，因此可靠的 Agent 會在每次狀態轉換後重新擷取快照：

agent-browser click @e3
agent-browser wait --load networkidle
agent-browser snapshot -i

等待 networkidle 並不適用於每個應用程式，因為分析、串流和輪詢可能會讓網路活動持續存在。如果存在可觀測的應用程式條件，應優先等待該條件：

agent-browser wait "#account-dashboard"
agent-browser wait --url "**/account"

snapshot 文件也說明了單層 iframe 展開。子參照會保留框架上下文，因此命令可以直接操作可存取 iframe 中的元素，而不需要單獨切換框架。無法存取無障礙樹的跨來源框架會被省略。

無障礙資訊不會編碼所有視覺事實。Canvas 內容、未標示的圖示、重疊元素和版面配置缺陷都需要像素資訊。帶註解的螢幕擷取會疊加對應於 @e2 的 [2] 等標籤：

agent-browser screenshot --annotate page.png

因此，快照應驅動語意互動，而當語意資訊不足時，螢幕擷取則提供視覺證據。

工作階段、設定檔與狀態 #

具名工作階段可以隔離瀏覽器執行個體：

agent-browser --session buyer open https://shop.example
agent-browser --session admin open https://admin.example
agent-browser session list

每個由本機管理的工作階段都擁有獨立的 Cookie、儲存空間、歷史記錄和驗證狀態。透過 CDP 連接到同一個現有 Chrome 的工作階段是例外，因為它們共享同一個 Chrome 執行個體，並繫結至不同分頁。--pin-tab 可防止繫結的分頁關閉後，工作階段悄悄移動到另一個分頁。

三種持久化機制分別解決不同問題：

機制	用途
具名工作階段	隔離並行的瀏覽器執行個體
`--profile`	匯入瀏覽器設定檔或使用持久化設定檔目錄
`--state` 或 `--restore`	儲存並重新載入 Cookie 和 Web Storage

僅有工作階段名稱並不能讓資料在精靈關閉後持續存在。將 --session <name> 與 --restore 結合，可在 ~/.agent-browser/sessions/ 下啟用自動載入狀態和定期儲存。

狀態檔案包含驗證資料，因此不得進入原始碼控制。設定 64 字元的十六進位 AGENT_BROWSER_ENCRYPTION_KEY 後，可以使用 AES-256-GCM 加密還原狀態。工作階段指南說明了設定檔複製行為、自動儲存時機、到期和加密。

設定與部署後端 #

設定會按照優先權由低到高解析：

~/.agent-browser/config.json；
./agent-browser.json；
AGENT_BROWSER_* 環境變數；以及
命令列旗標。

專案發布了官方 JSON Schema，因此可以透過編輯器或 CI 工作驗證專案設定。

本機執行可以啟動無頭或有頭 Chrome。--executable-path 會選取特定的 Chromium 系列二進位檔。--cdp 則連接到本機連接埠、ws:// 或 wss:// 端點：

agent-browser --cdp 9222 snapshot
agent-browser --cdp "wss://browser.example/cdp?token=..." snapshot

提供者模式會將瀏覽器基礎設施移至支援的服務，同時保留相同的 CLI：

BROWSERBASE_API_KEY=... \
  agent-browser --provider browserbase open https://example.com

遠端執行適用於 CI 和無伺服器環境，但信任邊界會改變。提供者憑證、瀏覽器工作階段保留、跨區域輸出流量以及提供者端的啟動行為都會成為部署考量。CDP 偵錯端點也授予對其瀏覽器的廣泛控制權，因此不得暴露給不受信任的網路。

安全性需要明確設定 #

agent-browser 的所有安全功能都是選擇啟用。預設執行不會限制導覽、操作或輸出。因此，正式環境部署應將控制措施定義為 Agent Harness 的一部分：

json

{
  "$schema": "https://agent-browser.dev/schema.json",
  "contentBoundaries": true,
  "maxOutput": 50000,
  "allowedDomains": [
    "app.example.com",
    "*.app.example.com",
    "cdn.example.net"
  ],
  "actionPolicy": "./agent-browser-policy.json"
}

嚴格的動作原則可以允許觀察和一般導覽，同時拒絕程式碼執行與檔案傳輸：

json

{
  "default": "deny",
  "allow": [
    "navigate",
    "snapshot",
    "click",
    "scroll",
    "wait",
    "get"
  ]
}

這些控制措施分別處理不同威脅：

內容邊界使用隨機 nonce 和來源中繼資料包覆頁面衍生輸出，協助協調器區分不受信任的頁面文字與工具框架內容。
網域允許清單會阻擋不允許的導覽和子資源，並在支援的 Chromium 工作階段中停用 WebRTC。
動作原則允許或拒絕 eval、upload、download、network 和 state 等類別。
確認機制會將選定的類別置於協調器或互動式核准之後。
輸出限制限制頁面衍生資料造成的上下文淹沒。
驗證資料保管庫會加密儲存的憑證，並使密碼不出現在一般精靈 IPC 和 Agent 可見的輸出中。

內容邊界屬於縱深防禦，而不是模型會忽略提示注入的證明。網域篩選不是作業系統防火牆，WebSocket 或 EventSource 攔截也只是盡力而為。因此，強隔離應將 agent-browser 原則與容器限制、檔案系統權限、網路輸出政策和範圍嚴格限定的憑證結合。

網域允許清單會刻意拒絕數種組合，包括預先存在的 CDP 連接、設定檔、還原狀態和 Safari/iOS 後端，因為這些模式可能在精靈建立隔離之前執行現有內容。必要的 CDN、字型、API 和身分提供者網域也必須出現在允許清單中，否則網站將無法載入。

在 agent-browser 與 Playwright 之間選擇 #

agent-browser 與 Playwright 在不同的抽象層運作：

需求	較適合的介面
AI Agent 必須透過 Shell 工具檢查和操作任意頁面	agent-browser
測試套件需要斷言、fixtures、重試、並行工作者和報告	Playwright
工作流程需要精簡的觀察結果和元素參照	agent-browser
程式碼需要涵蓋 Firefox、WebKit 和 Chromium	Playwright
應用程式需要具型別的瀏覽器邏輯與受原始碼控制的選擇器	Playwright
Agent 需要逐命令持久化的瀏覽器狀態	agent-browser

Playwright 是端對端測試框架與瀏覽器自動化函式庫；agent-browser 是供 Agent 循環使用的命令介面。由於 fixtures、斷言、追蹤工具和多引擎涵蓋屬於程式碼，Playwright 仍然更適合確定性的測試程式。agent-browser 將從觀察到動作的轉換降至最低，因此適合開放式 Agent 工作。

Browser Use 是另一個不同的層次。agent-browser 可以透過 --provider browseruse 將 Browser Use 作為託管瀏覽器提供者，但該整合不會讓兩個專案在功能上等價。當所需介面是由遠端瀏覽器支援的 agent-browser 命令時，請選擇提供者整合；當所需的應用程式介面是 Browser Use 的 SDK 和 Agent API 時，則直接使用 Browser Use。

營運指引 #

可靠的部署應遵循以下規則：

固定 agent-browser 版本，因為命令行為和後端支援會持續演進。
在導覽或 DOM 變更後重新擷取快照，因為元素參照描述特定的頁面狀態。
等待應用程式可觀測的條件，而不是假設固定延遲或通用的 networkidle。
按工作和主體分隔工作階段，然後避免將隔離的工作連接到同一個 Chrome 執行個體。
將螢幕擷取、下載內容、視訊、HAR 檔案、設定檔和儲存狀態視為可能包含敏感資訊的產物。
明確啟用內容邊界、輸出限制、動作原則和網域限制。
在瀏覽器程序以下的層級強制執行檔案系統和網路隔離，因為 CLI 層級的原則不能取代作業系統沙箱。

agent-browser 不會讓瀏覽器 Agent 變得具確定性。頁面仍會變更，驗證會過期，無障礙中繼資料可能不完整，而模型決策仍然具有機率性。agent-browser 提供的是更窄且更具狀態性的介面：瀏覽器不再是從頭產生的一組腳本，而是具有精簡觀察結果、明確參照和可強制執行動作類別的持久化工具。