作者注：從安裝到 snapshot、ref 操作、結果校驗，5 步掌握 agent-browser 的「讀頁面、點元素、再讀頁面」循環，讓 AI Agent 穩定驅動真實瀏覽器。
讓 AI Agent 操作網頁，常見的難點在於它看不到頁面，也很難穩定地點中目標元素。截圖加座標點擊的方案消耗大量 token，還容易點偏；直接把整段 HTML 交給模型，上下文很快就會被撐滿。本文介紹 agent-browser 的 snapshot-ref 操作循環，幫助你掌握讓 Agent「一次一條命令」驅動瀏覽器的方法。
這不是又一篇瀏覽器自動化框架的概念科普，下面按實際上手順序，拆解 agent-browser 的安裝、snapshot 與 ref 的配合、失敗重試策略，以及如何把它接入 Agent 工作流。
核心價值：讀完本文，你將理解 agent-browser 的 snapshot-ref 循環爲什麼適合大模型，並能在自己的 Agent 中用 5 條命令跑通第一個瀏覽器任務。
agent-browser snapshot-ref 循環核心要點
agent-browser 是 Vercel Labs 開源的瀏覽器自動化工具，採用 Apache-2.0 協議。它是一個原生 Rust CLI，目標很明確：給 AI Agent 一個能逐條命令驅動的瀏覽器。Agent 打開頁面後，把頁面讀成無障礙樹（accessibility tree）形式的緊湊文本，再通過 shell 命令對元素執行操作。
| 要點 | 說明 | 對 Agent 的價值 |
|---|---|---|
| snapshot 緊湊文本 | 頁面以無障礙樹形式輸出，每個元素帶 @e1 這類 ref |
比截圖和原始 HTML 更省上下文 |
| ref 精準定位 | 操作命令直接引用 ref，如 click @e1 |
不必讓模型自己拼 CSS 選擇器 |
| 瀏覽器常駐 | 後臺守護進程保持瀏覽器打開 | 每一步只是一次簡短的 shell 調用 |
| 失敗顯式報錯 | 元素被遮擋、隱藏、禁用時點擊會失敗而非假成功 | Agent 能根據真實反饋決定下一步 |
| 自帶 skills | CLI 內置與版本匹配的使用說明 | Agent 讀到的指令與已安裝版本一致 |
snapshot-ref 循環的工作方式
這個循環可以概括爲三個動作：先 snapshot 讀頁面，再對某個 ref 執行操作，然後再次讀取頁面確認結果，如此往復。官方給出的 example.com 快照只有一行：- link "Learn more" [ref=e1]。模型看到這一行，就知道頁面上有一個名爲 Learn more 的鏈接，並且可以用 @e1 去點擊它。
這種設計把「理解頁面」和「執行動作」拆成兩個可驗證的步驟，非常契合大模型的工具調用模式。模型不需要理解複雜的 DOM 結構，只需在文本里找到語義正確的元素，再引用對應的 ref 即可。每次操作後重新快照，也讓 Agent 始終基於最新的頁面狀態做判斷，而不是靠記憶猜測。
agent-browser 的底層架構
CLI 本身並不直接持有瀏覽器。第一條命令執行時，會啓動一個後臺守護進程（daemon），守護進程通過 Chrome DevTools Protocol 控制瀏覽器，後續每條 CLI 命令都發給這個守護進程。所以瀏覽器在命令之間始終保持打開，登錄態、頁面位置都不會丟失。
每個 --session 擁有獨立的守護進程和瀏覽器，方便多個任務並行而互不干擾。默認情況下，無頭瀏覽器在連續一小時沒有收到命令後會被關閉，守護進程隨之退出；如果配置了會話持久化（session persistence），退出前會先保存狀態。
驅動這個循環的「大腦」是大模型。每一輪快照文本都會進入模型上下文，模型決定下一條命令，因此模型的指令遵循能力和單價直接影響任務成功率與成本。API易 提供本文涉及的 Claude、DeepSeek、Kimi 等模型的 API 調用，兼容 OpenAI 與 Anthropic 兩種接口格式，接入文檔見 docs.apiyi.com。
agent-browser 快速上手：5 步跑通 snapshot-ref 循環
第 1 步：安裝 agent-browser 與瀏覽器
最常見的方式是通過 npm 全局安裝，然後下載 Chrome for Testing。npm 包會根據宿主平臺自動選擇對應的原生二進制，目前覆蓋 macOS（ARM64、x64）、Linux（ARM64、x64，glibc 與 musl）以及 Windows（x64）。
| 安裝方式 | 命令 | 適用場景 |
|---|---|---|
| npm 全局安裝 | 先 npm install -g agent-browser，再 agent-browser install |
大多數開發環境，首次需下載瀏覽器 |
| Homebrew | 先 brew install agent-browser，再 agent-browser install |
macOS 用戶 |
| Linux 帶依賴 | agent-browser install --with-deps |
服務器、容器，需同時安裝瀏覽器系統庫 |
| 免安裝 | npx agent-browser open example.com |
臨時試用、CI 中一次性任務 |
| 維護命令 | agent-browser upgrade、agent-browser doctor |
升級版本、排查環境問題 |
如果要從源碼構建，官方要求 Node.js 24 及以上、pnpm 11 及以上以及 Rust 工具鏈。依次執行 pnpm install、pnpm build:source、pnpm link --global，最後運行 agent-browser install 即可。日常使用直接走 npm 安裝就夠了。
第 2 步到第 5 步：完整的最小循環
安裝完成後，下面這組命令就是一個完整的 snapshot-ref 循環。建議先在終端手動跑一遍，確認每一步的輸出，再交給 Agent 自動執行。
| 步驟 | 命令 | 作用 | 預期結果 |
|---|---|---|---|
| 2. 打開頁面 | agent-browser open example.com |
啓動守護進程並打開網址 | 瀏覽器常駐後臺 |
| 3. 讀取快照 | agent-browser snapshot -i |
只列出可交互元素，每個帶 ref | 輸出類似 link "Learn more" [ref=e1] |
| 4. 操作 ref | agent-browser click @e1 |
對快照中的元素執行點擊 | 頁面跳轉或狀態變化 |
| 5. 校驗結果 | agent-browser get url |
讀取當前 URL，確認動作生效 | 返回跳轉後的地址 |
| 收尾 | agent-browser close |
關閉瀏覽器 | 釋放資源 |
第 3 步裏的 -i 參數很關鍵，它只輸出可交互元素，能顯著縮短快照文本，特別適合 token 預算有限的場景。第 5 步的校驗也不能省，Agent 必須靠真實反饋判斷操作是否成功，而不是默認「點了就算成功」。
🚀 快速開始：跑通手動循環後，就可以把這組命令交給 Agent。建議先通過 API易 apiyi.com 獲取測試額度，用同一套任務分別試幾款模型，觀察誰更擅長從快照文本里挑出正確的 ref。接口兼容 OpenAI 與 Anthropic 格式，現有 Agent 框架基本只需替換密鑰和地址，具體以 docs.apiyi.com 文檔爲準。
agent-browser ref 的有效期與重新快照
ref 描述的是「快照那一刻」的頁面。頁面一旦發生導航或 DOM 變化，舊的 ref 就可能失效，甚至指向錯誤的元素。因此鐵律是：每次跳轉或頁面明顯變化後，先重新執行 snapshot，再使用新的 ref。
這條規則最好直接寫進 Agent 的系統提示詞。一個可靠的循環應該是「快照、操作、快照」，而不是「快照一次、連續操作十次」。多花一次快照的開銷，遠小於點錯元素後排查和回滾的成本。
agent-browser 點擊失敗時的處理策略
agent-browser 的點擊不會「假裝成功」。當目標元素被隱藏、被禁用、位於視口之外，或被其他元素遮擋（比如 Cookie 同意彈窗）時，click 會直接返回失敗。這對 Agent 非常友好，因爲錯誤信息本身就是下一步決策的依據。
| 失敗原因 | 典型表現 | 推薦處理 |
|---|---|---|
| 被遮擋 | 同意彈窗、浮層蓋住按鈕 | 先關閉遮擋元素，重新快照後重試 |
| 不在視口 | 元素在頁面下方 | 用 scroll 滾動，再重新快照 |
| 元素禁用 | 表單未填完導致按鈕不可點 | 先用 fill 補全必填項，再快照確認 |
| 元素隱藏 | 需展開菜單纔出現 | 先點擊展開入口，用 wait 等待後快照 |
| ref 過期 | 頁面已跳轉或刷新 | 重新執行 snapshot 獲取新 ref |
除了 ref，agent-browser 還支持 CSS 選擇器、文本、XPath 和語義化定位器。例如 agent-browser find role button click --name "Submit" 可以按角色和名稱找到提交按鈕並點擊。在頁面結構穩定、元素語義清晰的場景下，語義化定位器可以作爲 ref 的補充。
agent-browser 常用命令分組
agent-browser 的命令覆蓋面很廣，完整列表可以通過 agent-browser --help 查看，單條命令用 agent-browser <command> --help。下面按用途整理了最常用的幾組，方便你決定給 Agent 開放哪些能力。
| 分組 | 代表命令 | 典型用途 |
|---|---|---|
| 導航與讀取 | open、back、reload、read、snapshot、get、is |
打開頁面、讀快照、查詢狀態 |
| 交互 | click、fill、type、press、select、check、scroll、upload、find |
點擊、填表、上傳文件 |
| 等待 | wait |
等待元素出現或頁面加載 |
| 採集 | screenshot、pdf、record、download、diff |
截圖、導出 PDF、錄屏、頁面對比 |
| 頁面與網絡狀態 | cookies、storage、network、eval |
管理 Cookie、攔截網絡、執行腳本 |
| 標籤頁與彈窗 | tab、frame、dialog |
多標籤、iframe、對話框 |
| 調試與性能 | console、errors、trace、vitals、a11y |
抓取控制檯錯誤、性能指標 |
| 會話與認證 | session、state、auth、confirm、deny |
會話隔離、登錄態、敏感操作確認 |
| Agent 集成 | skills、mcp、flow、batch、plugin |
加載技能、啓動 MCP 服務 |
瀏覽器引擎方面，默認使用 Chrome for Testing。你也可以用 --cdp 或 --auto-connect 連接一個已在運行的 Chrome，用 --engine 切換到 Lightpanda 或 Obscura 引擎，在 iOS 模擬器裏驅動 Mobile Safari，或者接入 Browserbase、Browserless、Browser Use、Kernel、AgentCore 等雲瀏覽器服務。
把 agent-browser 接入 AI Agent
用內置 skills 教會 Agent
agent-browser 的一個巧妙設計是把使用說明隨 CLI 一起發佈。執行 agent-browser skills get core 會輸出核心循環、ref 用法、等待策略和常見工作流；加 --ref commands 只看某一份參考，比如完整命令列表；加 --full 則附帶完整命令參考和模板。agent-browser skills list 還能列出 electron、slack、dogfood 等專項技能。
在 Agent 框架裏，可以通過 npx skills add vercel-labs/agent-browser 安裝發現技能。這個技能只是一個很薄的引導，會讓 Agent 去加載 agent-browser skills get core，因此指令永遠和已安裝的 CLI 版本保持一致。如果不想裝技能，也可以在 AGENTS.md 裏寫一句：使用 agent-browser 做瀏覽器自動化，首次使用前先運行 agent-browser skills get core 並按其說明操作。
通過 MCP 接入
如果你的客戶端支持 MCP，執行 agent-browser mcp 會通過 stdio 啓動一個 MCP 服務器。這樣 Claude 類桌面客戶端或自研 Agent 就可以把瀏覽器操作當作標準工具調用，無需自己封裝 shell 執行層。
爲 snapshot-ref 循環選擇驅動模型
瀏覽器任務的特點是輪次多、每輪都帶一段快照文本，輸入 token 佔比通常遠高於輸出。因此選模型時，除了指令遵循能力，還要重點看輸入單價和緩存價格。下表價格均以 API易 價格頁 docs.apiyi.com/models 的實際數據爲準，單位與計費口徑請以價格頁標註爲準。
| 模型 | 輸入價格 | 輸出價格 | 緩存價格 | 適用角色 | 可用平臺 |
|---|---|---|---|---|---|
| claude-opus-5-5 | $4 | $20 | $0.2 | 複雜多步任務、疑難頁面 | API易 apiyi.com |
| claude-sonnet-5-5 | $2 | $10 | $0.1 | 日常主力驅動模型 | API易 apiyi.com |
| kimi-k3.1-pro | $2 | $10 | $0.2 | 中文網頁場景 | API易 apiyi.com |
| deepseek-v4.1-flash | $0.3 | $1.2 | $0.006 | 簡單表單、批量巡檢 | API易 apiyi.com |
一個實用的組合是：用 deepseek-v4.1-flash 處理結構簡單、步驟固定的批量任務，用 claude-sonnet-5-5 作爲通用主力，遇到複雜交互或頻繁失敗的頁面再升級到 claude-opus-5-5。由於 skills 文本和系統提示在每一輪都會重複出現，緩存價格較低的模型在長循環中更有成本優勢。
需要說明的是，文心 ERNIE 系列在 API易 價格表中暫時查不到，API易 目前暫未上線該模型，我們會盡快上線。如果你的 Agent 原本依賴 ERNIE，可以先用上表中的模型替代測試。
💡 選擇建議：沒有一款模型在所有網站上都最好。建議挑 3 到 5 個真實業務頁面做小樣本測試，在 API易 apiyi.com 上用統一接口切換模型，對比成功率和單任務成本後再定主力模型。
agent-browser 安全使用建議
讓 Agent 操作真實瀏覽器，安全邊界必須提前設計好。agent-browser 官方文檔的安全章節提供了認證保險庫（auth vault）、域名白名單、操作策略以及內容邊界等機制。命令層面，auth 用於管理登錄憑據，confirm 和 deny 用於對敏感操作進行確認或拒絕。
在生產環境中，建議至少做到三點：
- 限制可訪問域名：用域名白名單把 Agent 限制在業務相關的網站內，避免被頁面誘導跳轉到陌生站點。
- 憑據不進上下文：把賬號密碼放進 auth vault，而不是寫進提示詞，防止憑據出現在模型日誌裏。
- 敏感動作人工確認：支付、刪除、提交訂單這類操作配置爲需要確認，讓人類保留最終決定權。
網頁內容本身也可能包含針對 Agent 的惡意指令，所以內容邊界機制同樣值得開啓。它的作用是讓模型清楚區分「頁面裏的文字」和「用戶給的指令」，降低提示詞注入的風險。
常見問題 FAQ
Q1：什麼是 agent-browser 的 snapshot-ref 循環？
這是 agent-browser 的核心工作方式：先用 `snapshot` 把頁面讀成帶 ref 的緊湊文本，再對某個 ref 執行操作，然後重新快照確認結果，如此往復。它把頁面理解和動作執行拆成可驗證的小步，很適合大模型逐步推理。
Q2:agent-browser 和截圖驅動的瀏覽器 Agent 有什麼區別？
截圖方案在視覺理解上更通用，但 token 消耗大，座標點擊也容易偏移。相比之下，agent-browser 用無障礙樹文本加 ref 定位，上下文更緊湊，操作更精準，失敗時還會明確報錯，更適合需要穩定執行的自動化任務。
Q3：爲什麼頁面跳轉後舊的 ref 不能繼續用？
ref 只描述快照那一刻的頁面。導航或 DOM 變化後，元素可能已經消失或被替換，舊 ref 可能失效或指向錯誤元素。正確做法是每次頁面變化後重新 `snapshot`，再使用新 ref。
Q4:agent-browser 適合哪些應用場景？
主要適合以下場景：
– **表單自動填寫**：註冊、報名、後臺錄入等步驟固定的流程。
– **站點巡檢與迴歸測試**：結合 `errors`、`console`、`vitals` 檢查頁面錯誤和性能。
– **信息採集**：登錄後臺後按菜單逐頁讀取數據。
– **Electron 與 Slack 等專項場景**：通過 `skills list` 裏的專項技能擴展。
Q5：驅動 agent-browser 的模型該如何接入？
可以按以下步驟操作：
1. 訪問 API易 apiyi.com 註冊賬號並獲取 API Key。
2. 在 Agent 框架中選擇 OpenAI 或 Anthropic 兼容格式，按 docs.apiyi.com 文檔填寫接入參數。
3. 用本文的 5 步循環作爲測試任務，對比不同模型的表現。
API易 支持 Claude、DeepSeek、Kimi 等多種模型統一接入，切換模型只需改模型名。
Q6：運行 snapshot-ref 循環的模型成本怎麼估算？
瀏覽器任務以輸入 token 爲主，每輪都要帶上快照文本和系統提示。估算時重點看輸入單價和緩存價格，並儘量用 `snapshot -i` 縮短快照。各模型的實際單價請以 API易 價格頁 docs.apiyi.com/models 爲準，不要參考過時的第三方報價。
Q7:agent-browser 有哪些已知限制？
ref 的時效性要求 Agent 頻繁重新快照，輪次會因此增加。無障礙信息缺失嚴重的頁面，快照可能不夠完整，這時需要改用 CSS 選擇器、XPath 或截圖輔助。另外，無頭瀏覽器空閒一小時後會自動關閉，長時間任務需要配置會話持久化。
agent-browser snapshot-ref 核心要點 Key Takeaways
- 核心定義:agent-browser 是 Vercel Labs 開源的 Rust CLI，讓 Agent 逐條命令驅動瀏覽器。
- 核心循環：快照讀頁面、對 ref 執行操作、再快照校驗，三步不斷往復。
- ref 鐵律：頁面導航或 DOM 變化後，必須重新快照再使用 ref。
- 失敗即信號：元素被遮擋或禁用時點擊會報錯，Agent 應先處理遮擋再重試。
- 接入方式：用
skills get core加載版本匹配的指令，或用agent-browser mcp接入 MCP 客戶端。 - 安全優先：生產環境開啓域名白名單、auth vault 和敏感操作確認。
- 模型選擇：在 API易 apiyi.com 用統一接口對比驅動模型，價格以 docs.apiyi.com/models 爲準。
總結
agent-browser snapshot-ref 循環的核心要點：
- 用文本代替截圖：無障礙樹快照加 ref，讓模型以最少的上下文理解頁面。
- 一步一校驗：每次操作後讀取頁面或 URL，避免 Agent 在錯誤狀態上繼續執行。
- 失敗可處理：遮擋、視口、禁用、ref 過期都有明確的處理路徑。
- 接入成本低:npm 安裝、內置 skills、MCP 服務，三種方式都能快速接進現有 Agent。
建議先在終端手動跑通 open、snapshot、click、get、close 五條命令，再把循環規則寫進 Agent 的系統提示詞，最後用真實業務頁面挑選驅動模型。
推薦通過 API易 apiyi.com 快速驗證不同模型驅動 agent-browser 的效果，平臺兼容 OpenAI 與 Anthropic 接口格式，接入說明見 docs.apiyi.com，模型價格以 docs.apiyi.com/models 爲準。
📚 參考資料
- GitHub – agent-browser：官方開源倉庫
- 鏈接：
github.com/vercel-labs/agent-browser -
說明：包含安裝方式、快速上手、命令分組和開發說明
-
agent-browser 官方文檔：完整指南與命令參考
- 鏈接：
agent-browser.dev -
說明：覆蓋快照、選擇器、會話、CDP 模式和安全機制
-
agent-browser 安全文檔：認證與訪問控制
- 鏈接：
agent-browser.dev/security -
說明：介紹 auth vault、域名白名單、操作策略與內容邊界
-
API易 文檔中心：模型接入說明
- 鏈接：
docs.apiyi.com -
說明：OpenAI 與 Anthropic 兼容格式的接入方法
-
API易 模型價格頁：各模型實際計費
- 鏈接：
docs.apiyi.com/models - 說明：本文所有模型價格均以此頁爲準
作者:APIYI 技術團隊
技術交流：歡迎在 API易 apiyi.com 網站首頁聯繫我們，更多接入資料可訪問 docs.apiyi.com 文檔中心
