Browser Agent怎麼做？CDP、Playwright、Session、重試與操作證據

本文更新：2026 年 8 月 17 日。本次增量把 Browser Agent 的工作拆成瀏覽器連線、BrowserContext 隔離、authenticated session、CDP 能力、可恢復重試與操作證據；新增圖片是 YOLO LAB 原創生成的編輯概念圖，不是 Playwright、Chrome DevTools 或任何產品的官方介面截圖。

Browser Agent 不是「會點按鈕」就完成

瀏覽器代理真正要處理的，不只是找到按鈕、填入文字、等待頁面，而是要在一個會變動的環境裡完成可重複、可恢復、可交接的工作。一次成功點擊只能證明某個當下狀態下的動作成功；如果沒有記錄使用了哪個 session、看見哪個 DOM、收到哪個網路回應、最後頁面呈現什麼內容，就很難知道下一次失敗是因為登入過期、元素改名、網路延遲，還是前一步其實沒有完成。

因此，Browser Agent 可以拆成五個層次：連線層決定控制哪個瀏覽器；隔離層決定不同任務是否互相污染；操作層決定如何定位與互動；恢復層決定什麼錯誤能重試；證據層則把最後結果變成截圖、trace、DOM、URL、時間戳或 API 回應。少了任何一層，系統可能仍然「看起來能跑」，卻不適合長時間自治。

本文以 Playwright 官方文件和 Chrome DevTools Protocol 官方文件作為概念基礎。它們能支持 API 和邊界的描述，但不等於任何特定 Agent Framework、MCP server 或本機環境已經被本文實際驗證。讀者要把範例部署到自己的系統，仍需自行確認瀏覽器版本、權限、登入狀態、網路策略與資料安全。

CDP、Playwright 與一般瀏覽器自動化的分工

Chrome DevTools Protocol 是 Chromium 系列瀏覽器提供的一組通訊協定，讓工具可以對 DOM、Network、Page、Runtime、Browser 等 domain 發送命令並接收事件。它比較像瀏覽器的低階控制面：能力細、事件多、能接近瀏覽器內部狀態，但也代表使用者需要處理 target、session、版本差異與生命週期。

Playwright 則提供較高階的瀏覽器自動化 API，例如 browser、BrowserContext、page、locator、request、trace 等物件。對多數測試與 Agent 任務來說，Playwright 的價值不只是把 CDP 包起來，而是提供等待、定位、隔離、下載、截圖與測試 runner 等比較完整的工作模型。Playwright 也能在 Chromium 上建立 CDP session，但那不表示所有 Playwright 功能都必須直接改寫成 CDP 命令。

選擇方式可以很務實：若任務是登入網站、操作表單、等待可見狀態並保存結果，先用 Playwright 的高階 API；若需要讀取特定 Chrome domain、接上已啟動的 Chromium、監看網路或做瀏覽器級診斷，再引入 CDP。直接把所有事情都降到 CDP，會讓簡單任務承擔更多版本和錯誤處理成本。

BrowserContext 是 Agent 隔離的基本單位

Playwright 官方把 BrowserContext 描述成彼此獨立的瀏覽器 session，類似輕量、隔離的 incognito profile。每個 context 可以有自己的 cookies、local storage、permissions、頁面與下載狀態。對 Browser Agent 而言，這個邊界很重要：任務 A 登入的網站不應意外把 cookie、購物車、草稿或權限帶到任務 B。

一個穩定的工作流程通常是「一個任務一個 context」，而不是「整個 Agent 永遠共用一個 page」。任務開始時建立 context，載入必要的 authenticated state，完成操作與證據輸出後關閉 context。關閉不是形式上的清理；它能幫助保存 trace、HAR、video 等 artifact，也能避免上一個任務留下的狀態影響下一次結果。

如果為了效率而共用 context，就要明確定義共享邊界。例如唯讀查詢可以共用一個不會改變 server state 的 session，但涉及購物、發文、付款、設定或權限的工作，應使用不同帳號或不同 context。Playwright 官方 authentication 文件也提醒，保存的 storage state 可能含有可冒用帳號的 cookies 和 headers，不應提交到公開或不受控的 repository。

隔離還要延伸到檔案與輸出：auth state、trace、下載檔、截圖、錯誤 HTML 都應依任務 ID 或 worker ID 命名，不要所有 Agent 寫入同一個 `latest.json`。如果兩個任務同時覆蓋同一份證據，最後即使頁面操作成功，也無法判斷證據屬於哪一次執行。

Session 不只是 cookie：登入狀態的生命週期

很多 Browser Agent 失敗都被簡化成「重新登入就好」，但 session 可能包括 cookies、local storage、IndexedDB、權限、CSRF token、session storage 和 server-side account state。Playwright 的 storage state 能保存許多常見的 authenticated browser state，但 session storage 不會自動在頁面載入間持久化，特殊網站仍需要明確保存與注入。

建立 session 時，先回答三個問題：這個狀態屬於哪個帳號？有效多久？哪一種請求會使它失效？如果 Agent 在登入頁遇到 401、403、二次驗證或空白頁，不能無限重試密碼或盲目刷新。更安全的策略是停止任務、保存非敏感的錯誤證據、要求重新授權，並把原 session 標記為 expired。

讀取與保存 auth state 也要遵守最小權限。唯讀任務不需要取得發文或付款權限；對不同網站應使用不同 state 檔案；state 檔案要放在受控且被 gitignore 的目錄；log、trace 和 screenshot 要遮蔽 token、cookie、個資與頁面中的秘密。Chrome DevTools 的 auto-connect 類能力尤其要小心，因為連上現有瀏覽器可能接觸開啟的分頁、cookies、local storage 和瀏覽器擴充功能。

定位與等待：Agent 要等待狀態，不是等待秒數

固定等待 3 秒只能讓流程變慢，不能保證頁面真的完成。頁面可能在三秒內完成，也可能需要十秒；更麻煩的是 DOM 已出現，但資料仍在載入，或按鈕可見卻被 overlay 擋住。比較可靠的做法，是等待能代表任務狀態的訊號：某個角色元素可見、URL 已變成預期路徑、回應狀態是 200、表格列數增加、按鈕從 disabled 轉為可用，或頁面出現明確的成功訊息。

Locator 的語意也比脆弱的 CSS 路徑更重要。優先使用 role、label、text 或穩定的 data-testid，並在操作前確認元素數量與可操作狀態。若頁面有多個同名按鈕，不要直接取第一個；要先縮小容器、核對上下文，再執行 click。Agent 的動作越接近「人類會如何確認」，越容易在改版後維持可理解性。

每個動作最好都有前置條件和後置條件。點擊「送出」之前，確認表單資料和按鈕狀態；點擊之後，確認 URL、通知、資料列或 API 回應。這些 assertion 不只是測試語法，而是 Agent 的安全閘門：沒有後置條件，就不能把下一步建立在「應該已完成」上。

CDP 連線與 target 管理：連上瀏覽器不代表連對頁面

CDP 官方文件說明，當 Chromium 以 remote debugging port 啟動時，可以透過 `/json/version`、`/json/list` 或 WebSocket endpoint 取得瀏覽器與頁面 target 資訊。這些 endpoint 很適合做診斷，但 Agent 不能只記住一個固定 websocket URL。瀏覽器重啟、分頁關閉、target 替換、popup 出現或 DevTools attach，都可能改變可用的 target。

連線流程應先取得 browser version 和 target inventory，再以 URL、title、type 或明確 target ID 確認要控制的頁面。若頁面會開 popup，應在操作前註冊等待新 page；若有 iframe，則要分辨 frame 裡的 DOM 和主頁 DOM。若收到 `Inspector.detached`，應把它記為連線中斷與原因，而不是自動把任意新分頁當成原工作繼續。

CDP 的 tip-of-tree protocol 變化頻繁、沒有完整向後相容保證；這也是為什麼低階命令要有版本檢查與 fallback。對需要跨 Chrome 版本運作的 Agent，應把 CDP 能力包成小型 adapter，為每個 command 定義輸入、輸出、最低版本和失敗行為，不要在各個任務腳本裡散落 raw JSON。

重試不是把同一個 click 再做三次

Playwright 官方把 retry 視為重新執行失敗測試的機制，失敗 worker 和 browser 會被丟棄，再以新的 worker 繼續。這個概念對 Browser Agent 很有啟發：重試之前，應該重建乾淨的 context、重新取得必要狀態，並判斷前一次是否已經造成 server-side mutation。若前一次已成功送出表單，只是 response timeout，再送一次可能會重複下單、重複發文或重複扣款。

可以把錯誤分成三類。可重試錯誤包括短暫網路斷線、瀏覽器啟動失敗或明確的等待逾時，但前提是操作冪等且沒有未知的 server mutation。不可重試錯誤包括權限不足、資料驗證錯誤、資源不存在、帳號被鎖或安全政策拒絕。需要人工或重新授權的錯誤包括 MFA、CAPTCHA、付款確認和身份驗證。

每次 retry 都要有上限、退避與新 evidence。若第一輪失敗、第二輪成功，結果應標記為 flaky 或 recovered，而不是只輸出 passing；如果第三輪仍失敗，要保留各輪的 URL、錯誤分類、trace 路徑與最後頁面狀態。這樣維運者才能區分偶發網路問題和穩定的產品缺陷。

Trace、截圖與 DOM：什麼才算操作證據

操作證據不是「Agent 回答我成功了」。最小證據包至少應包含任務 ID、開始與結束時間、目標 URL、context／worker 識別、操作摘要、最後狀態、關鍵 assertion 結果，以及必要時的 screenshot、DOM snapshot、network response 或 trace。證據要能讓另一個人重建發生了什麼，而不是只留下模型的自然語言總結。

Playwright Trace Viewer 能把操作期間的 snapshot、截圖、網路與時間線集中到可檢查的 trace 中；官方文件建議在 CI 的第一次 retry 保存 trace，因為每次都保存會產生較高成本。對 Agent 來說，可以採用分級策略：成功的唯讀任務只保存摘要與最後畫面；失敗或重試的任務保存完整 trace；高風險寫入則在前後都保存狀態與回應。

證據本身也需要隱私政策。截圖可能含有姓名、地址、訂單、token 或私人訊息；trace 可能含有完整 request header 和 cookie。保存前應遮蔽敏感欄位、限制 retention、設定檔案權限，不要把 raw trace 上傳到公開 issue 或聊天頻道。可驗證不等於可以暴露所有資料。

一個可交接的 Browser Agent pipeline

1. Preflight：確認瀏覽器版本、目標 URL、帳號權限、任務 policy、預期狀態與是否已有同一任務在執行。
2. Context：建立隔離 BrowserContext，載入最小必要的 authenticated state，設定 timeout、locale、viewport 與下載政策。
3. Observe：先讀取頁面標題、URL、關鍵 DOM、權限提示與網路狀態，確認真的在正確 target。
4. Act：以 locator 和明確前置條件執行單一步驟，避免把整串 click 壓成不可觀察的黑盒。
5. Assert：確認後置狀態、資料變化、通知、回應或 URL；若不符合，停止後續寫入。
6. Evidence：輸出 screenshot、trace、DOM、錯誤分類與摘要，清理敏感資料並寫入唯一任務目錄。
7. Recover：只有在錯誤可重試且操作冪等時，以新 context 和新的 evidence 進行有限 retry。
8. Close：關閉 page、context 與 browser，確認 artifact 已 flush，再回傳「通過、恢復、失敗或需人工」的狀態。

這個 pipeline 的價值，是把 Agent 的「智能」放在選擇與判斷，而不是讓每一層都依賴猜測。模型可以決定下一步，但每一步都要被環境狀態、權限、assertion 和 evidence 約束。當任務需要寫入外部系統時，還應增加 preview、確認、備份與 read-back，不要因為瀏覽器可以點擊就跳過資料安全。

給搜尋與生成式引擎的短答案

• Browser Agent 的核心是什麼？不是單純自動點擊，而是把瀏覽器連線、隔離 session、操作、後置驗證、有限重試與可檢查證據串成完整流程。
• CDP 和 Playwright 怎麼分工？Playwright 適合高階頁面操作、context 隔離與測試；CDP 適合 Chromium 的低階 domain、target、Network 與診斷能力。
• 為什麼要用 BrowserContext？它能隔離 cookies、local storage、權限與頁面狀態，降低不同任務互相污染和失敗傳染的風險。
• 瀏覽器操作失敗可以一直 retry 嗎？不行。要先判斷是否已發生 server-side mutation、錯誤是否可重試、操作是否冪等，再以新 context、上限和退避執行。
• 什麼才是操作證據？至少要有任務識別、URL、時間、狀態、assertion 與必要的 screenshot、DOM、network 或 trace；不能只依賴 Agent 的成功文字。
• 本文新增圖片是官方介面截圖嗎？不是，是 YOLO LAB 原創概念圖，不代表 Playwright、Chrome DevTools、CDP 或任何產品的實際 UI。

官方來源與圖片 provenance

本文以Playwright Authentication核對 authenticated browser state、storage state、session storage 與敏感 cookies 的注意事項；以Playwright BrowserContext isolation核對 context 的隔離模型；以Playwright Retries核對 retry、worker 重建與 flaky 結果分類；以Chrome DevTools Protocol 官方文件核對 CDP domain、target、WebSocket endpoint、版本變動與連線能力。本文的 pipeline、風險分層與 evidence 設計屬 YOLO LAB 編輯整理，不代表任何框架的完整官方最佳實作。

新增圖片為 YOLO LAB 原創生成編輯概念圖，沒有使用 Playwright、Chrome、DevTools、MCP 或其他品牌的官方截圖、Logo、產品介面或程式碼畫面。圖片的 alt 與 figcaption 只描述 context、CDP、重試與 trace 的抽象關係；它不證明任何實際執行成功、瀏覽器版本相容性、登入狀態或安全性。