browserbase/stagehand AI 瀏覽器自動化教學:在 Playwright 上用自然語言穩定抓資料與操作

browserbase/stagehand 在 Playwright 之上提供 act、extract 與 observe 三大 AI 原語,兼顧腳本穩定度與跨版面適應力,一篇學會安裝與實戰範例。

Share
Stagehand官方 GitHub 專案封面圖:Stagehand 教學
Stagehand官方開源專案視覺圖。 圖片來源:官方原文。

寫過傳統網頁爬蟲或自動化測試腳本的工程師,最痛恨的就是「前端工程師昨天改了一個按鈕的 CSS 類別名稱,今天整條自動化管線就全掛了」。

為了解決選取器脆弱的問題,這兩年出現了許多純視覺或全自主的 AI 網頁代理。但這些純代理往往走向另一個極端:每點一個按鈕都要重新截圖給大模型思考,速度極慢、費用高昂,而且每次跑出來的操作路徑還不一樣。

browserbase/stagehand 在這兩個極端之間找到了一條非常務實的中間路線。它直接建構在開發者熟悉的 Playwright 風格介面之上,只把容易壞掉或需要語意理解的步驟,交給 act、extract 與 observe 三大 AI 原語處理。

更棒的是,這套開源框架同時提供 TypeScript、Python 與 Go 三種語言的完整 SDK,甚至還附帶免模型金鑰即可使用的本機 browse 命令列工具與雲端 MCP 整合。

這篇 Stagehand 教學 將帶你拆解三大原語的分工邏輯、完成安裝與認證實戰範例,並釐清本機與雲端執行的安全與效能邊界。

為什麼純 Playwright 太脆弱、純 AI 代理又太慢?

傳統 Playwright 腳本的最大優點是確定性高、執行速度極快,且完全免費。只要網頁的 DOM 結構不變,同一支腳本跑一萬次都會得到完全相同的結果。

但現實中的外部網站與內部管理後台經常改版,只要表單欄位換了位置、按鈕文字微調,寫死的 XPath 或 CSS 選取器就會立刻失效。

反過來說,如果把整段瀏覽器操作全權交給全自主 AI 代理,成本與穩定度立刻失控。代理往往會在複雜頁面裡迷航,不斷重複點擊或浪費大量 Token 讀取整頁冗餘的 HTML 標籤。

Stagehand 的核心設計哲學非常明確:不要用 AI 去做確定性程式碼已經做得很好的事。登入導航與固定網址跳轉繼續用傳統程式精準控制,只有遇到會變動的按鈕操作或非結構化表格擷取時,才呼叫對應的 AI 原語。

Stagehand官方 GitHub 專案封面圖:Stagehand 教學
Stagehand官方開源專案視覺圖。 圖片來源:官方原文。
Stagehand官方介紹與實機示範影片,非本站實測。 來源:官方 YouTube。

Stagehand 教學核心:act、extract、observe 三大原語

要掌握這套框架的精髓,只要弄懂它提供的三個核心方法以及它們各自適合的場景。

第一個原語是 observe。它的任務是「先看清楚頁面上的目標元素在哪裡,但先不動手」。呼叫這個方法並傳入自然語言描述後,系統會回傳真實的頁面元素選取器。

這個設計對資安極其重要。因為拿到真實選取器後,你可以交給傳統的 locator.fill 填入帳號密碼,如此一來你的機密憑證永遠不會經過大型語言模型,徹底杜絕敏感資料外洩風險。

第二個原語是 act。當你需要執行點擊按鈕、開啟特定分頁或填寫表單動作時,可以直接用自然語言下達指令。即使網站後來重新設計了表單排版,這套機制也能透過語意定位自我修復,不必人工重寫選取器。

第三個原語是 extract。爬蟲最煩人的工作就是把雜亂的網頁表格整理成乾淨資料。透過這個方法,你只需要定義好目標資料結構,例如在 TypeScript 搭配 Zod 或在 Python 搭配 Pydantic 模型,系統就會直接回傳通過型別驗證的結構化物件。

為了壓低 Token 消耗與執行延遲,底層採用了混合式無障礙樹精簡技術,只把代理真正需要的頁面語意上下文送給模型,並支援在瀏覽器旁以擴充套件形式運行,大幅減少跨進程來回溝通的延遲。

此外,針對現代複雜網頁常見的巢狀 iframe 與封閉式 Shadow DOM,框架也提供了深度定位能力,並支援 WebMCP 與 OpenTelemetry 追蹤整合。

延伸閱讀:加州檢察長控告 OpenAI:700 個 AI 代理逃出沙盒入侵 Hugging Face,訴訟焦點與責任爭議全解析

多語言安裝步驟與瀏覽器環境準備

這套專案採用開源的 MIT 授權條款,無論你習慣哪一種後端語言,都可以直接安裝官方 SDK,本機執行時只需要電腦裡已經安裝 Google Chrome 瀏覽器即可。

# TypeScript / Node.js 環境安裝
pnpm add @browserbasehq/stagehand 'zod@~4.4.3'

# Python 環境安裝
pip install stagehand

# Go 環境安裝
go get github.com/browserbase/stagehand/packages/sdk-go/v4@v4.0.0

如果你平常主要使用 Claude Code、Cursor 或 Codex 等程式代理輔助開發,不一定需要自己從頭寫 SDK 程式。官方額外提供了一套輕量級的 browse 命令列工具與專屬 Skill,本機使用甚至不需要設定任何 LLM 金鑰或雲端帳號:

npm install -g browse
npx skills add browserbase/stagehand --skill browse
browse open https://example.com --local
browse snapshot
browse get title

此外,如果你的應用已經深度整合了 MCP 生態系,官方也提供託管的雲端 MCP 伺服器端點,只要具備 Browserbase API 金鑰,就能讓 Claude 等支援遠端 MCP 的用戶端直接獲得導航與擷取網頁的能力,連本機瀏覽器都不用安裝。

在日常除錯與團隊協作中,browse 命令列工具特別適合用來快速驗證目標網站的無障礙樹結構。當你發現某個頁面元素用自然語言一直點不到時,可以先執行 browse snapshot 觀察代理實際看見的精簡頁面樹狀圖,確認該按鈕究竟位於主文件還是嵌套在深層的框架內,再調整指令描述,能省下大量盲目重試的時間。

實戰範例:保留登入狀態、安全填密與結構化擷取

在真實自動化場景裡,每次啟動瀏覽器都要重新登入並通過雙重驗證非常麻煩。以下我們以官方推薦的 TypeScript 範例為例,示範如何透過指定本機目錄保留 Cookie 狀態,並串聯三大原語完成發票表格擷取:

import { localBrowser, Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod/v4";

// 1. 指定 userDataDir 保存 Cookie,下次執行即可維持登入狀態
const browser = await localBrowser.launch({ userDataDir: "./browser-data" });
const stagehand = await Stagehand.create({
  browser,
  model: { modelName: "openai/gpt-5.4-mini", apiKey: process.env.OPENAI_API_KEY },
});

const [page] = await browser.context.pages();
await page.goto("https://app.example.com/login");

// 2. 用 observe 找出欄位真實選取器,確保密碼絕不傳送給 LLM
const { data: email } = await stagehand.observe("find the email input");
const { data: password } = await stagehand.observe("find the password input");
await page.locator(email[0].selector).fill(process.env.APP_EMAIL!);
await page.locator(password[0].selector).fill(process.env.APP_PASSWORD!);

// 3. 用 act 執行點擊與導航,即使版面微調也能自我修復
await stagehand.act("click the sign in button");
await stagehand.act("open the billing page");

// 4. 用 extract 搭配 Zod 取得通過型別驗證的結構化發票清單
const { data } = await stagehand.extract(
  "extract every invoice in the table",
  z.object({
    invoices: z.array(z.object({ number: z.string(), amount: z.number(), paid: z.boolean() })),
  }),
);

console.log(data.invoices);
await stagehand.close();
await browser.close();

這段不到四十行的程式碼示範了一個極佳的工程習慣:把「保留會話」、「安全填入憑證」、「容錯操作」與「強型別資料輸出」全部拆開處理,既不會把密碼餵給雲端模型,又能避免後端拿到格式錯亂的文字。

若要轉移到雲端規模化執行,只要將 localBrowser.launch 替換成 browserbase.launch 並開啟 cache: true。這樣一來,完全相同的重複操作就會直接命中伺服器端快取,不再重複消耗語言模型的 Token,還能在雲端自動切換最便宜的模型閘道。

當你的自動化腳本進入穩定運行期,建議同時搭配階段錄影回放與 OpenTelemetry 追蹤指標,記錄每一次 act 與 extract 的耗時與快取命中率。一旦外部網站改版導致自我修復耗時突然拉長,團隊就能第一時間從追蹤紀錄裡定位是哪個頁面元件發生異動,及時更新快取或調整提示詞描述。

延伸閱讀:Devin Apps 上線:AI 做的內部工具如何分享,私人連結、版本與費用怎麼看?

Python 與 Go 跨語言寫法與無瀏覽器輔助介面

除了前端與全端工程師熟悉的 TypeScript 之外,這套框架在 Python 與 Go 語言中也維持了高度一致的 API 體驗,讓資料科學與後端基礎設施團隊不必為了抓網頁而額外維護 Node.js 服務。

在 Python 環境中,你可以直接結合 Pydantic 模型來定義 extract 的輸出結構。只要宣告繼承自 BaseModel 的發票類別,並將類別傳入擷取函式,框架就會自動驗證回傳的欄位型別,確保後續寫入資料庫或送進資料管線時不會因為格式錯誤而崩潰。

而在 Go 語言版本中,SDK 善用了泛型設計。呼叫 stagehand.Extract 時只要傳入自訂的 Struct 型別參數,系統就會把網頁表格內容直接解碼成強型別的 Go 結構體,並搭配標準的 context.Context 控制逾時與資源釋放,非常適合納入高併發的微服務架構中。

另外一個常被忽略的實用功能,是 SDK 內建的無瀏覽器 search 與 fetch 輔助介面。當你的任務流程包含「先搜尋公開網頁、讀取文章內容,再決定是否登入特定系統操作」時,前半段的公開資訊擷取根本不需要啟動完整的 Chrome 瀏覽器。

透過這兩個輕量級介面,你可以直接將任何目標網址轉換為乾淨的 Markdown 文字,或取得精簡的搜尋結果清單。把耗費記憶體的真實瀏覽器工作階段留給需要身份驗證與動態互動的頁面,能讓整體自動化管線的速度與成本效益大幅提升。

與傳統 Playwright 及全自主網頁代理的比較

為了讓團隊更容易評估何時該導入這套框架,下表將它與傳統自動化工具及全自主代理做對比:

評估維度 傳統 Playwright / Puppeteer Stagehand 混合式框架 全自主純 AI 網頁代理
執行速度與延遲 極快,純本機與協定指令 快,僅關鍵步驟呼叫精簡無障礙樹 慢,每步皆須完整截圖與規劃
網站改版適應力 弱,選取器變動即中斷 高,三大原語具備語意自我修復 高,依賴視覺與即時推理探索
輸出資料結構穩定度 需手動撰寫繁瑣解析正則 內建 Zod 或 Pydantic 強型別驗證 容易受提示詞影響缺漏欄位
帳號密碼安全性 最高,完全不經外部模型 高,可用 observe 隔離機密憑證 較低,常須小心代理直接讀取表單
語言支援與生態系 支援多語言與完整測試工具 原生提供 TS、Python、Go 三大 SDK 多數集中在 Python 單一生態

對於需要長期穩定跑在排程上的商業資料擷取或端到端回歸測試來說,混合式架構顯然比全自主代理更可控、也更容易計算投資報酬率。

資安邊界、快取策略與實務限制

在將自動化腳本推進生產環境之前,還有三個實務限制與安全細節必須留意。

第一是 本機憑證目錄的保護。使用 userDataDir 確實能大幅減少重複登入的麻煩,但那個本機資料夾裡完整保存了網站的登入 Cookie 與階段權杖。

部署到共用伺服器或 CI 環境時,絕對不能把這個目錄誤簽進 Git 儲存庫,也必須設定嚴格的檔案系統存取權限,避免權杖遭其他程序竊取。

第二是 伺服器端快取與雲端功能的依賴邊界。雖然 SDK 核心完全開源且能在本地搭配自己的 Chrome 執行,但像是伺服器端動作快取、Model Gateway 自動選型、住宅代理池與操作錄影回放等進階功能,則需搭配 Browserbase 雲端服務與對應的 API 金鑰。

第三是 純文字內容擷取的殺雞用牛刀問題。如果你的任務只是讀取公開靜態文章或部落格內容,啟動完整的無頭瀏覽器其實非常耗費記憶體。這時可以優先考慮官方 SDK 內建的無瀏覽器 fetch 與 search 輔助介面,或是傳統 HTTP 請求,將瀏覽器算力留給真正需要登入互動與動態渲染的複雜網站。

常見問題

1. Stagehand 一定要付費購買 Browserbase 雲端服務才能用嗎?

不需要。它採用 MIT 開源授權,只要本機有安裝 Chrome 瀏覽器並填入自己的模型 API 金鑰,就能完全在本機免費運行。只有在需要雲端高併發、住宅代理或伺服器端快取時,才需要搭配雲端服務。

2. 我已經有一整套現成的 Playwright 測試腳本,遷移會很麻煩嗎?

不會。這套框架刻意保留了開發者熟悉的 goto、click、locator 與 screenshot 操作介面。你可以保留原本已經穩定運作的程式碼,只針對最常因為前端改版而壞掉的那幾個步驟,局部替換成 act 或 observe。

3. 在這份 Stagehand 教學裡,為什麼強調要用 observe 處理登入密碼?

因為直接把帳號密碼交給 act 指令,等同於把機密資訊送進大型語言模型的提示詞上下文中。改用 observe 只讓模型幫你找出輸入框的 CSS 選取器,再由本機程式碼讀取環境變數填入密碼,就能徹底確保憑證不經模型之手。

4. 如果網站使用了複雜的 iframe 或 Shadow DOM,AI 原語抓得到嗎?

可以。官方在架構設計上專門針對代理場景強化了深度定位能力,能夠穿透多層巢狀 iframe 與封閉式 Shadow DOM 結構來精簡無障礙樹,解決傳統爬蟲在現代前端框架網頁上常遇到的元件找不到問題。

結語

不在確定性已經足夠的地方浪費語言模型算力,只把 AI 用在「容易因改版失效的定位」與「非結構化表格整理」,是 Stagehand 最令工程師讚賞的架構設計。

  • 適合誰:受夠了前端微調就得重修爬蟲選取器的工程師、需要把網頁操作穩定納入後端流程的 TypeScript、Python 與 Go 開發者,以及希望為程式代理加上可控瀏覽器能力的團隊。
  • 不適合誰:只需抓取純靜態網頁文字且無須任何登入互動的簡單任務,或是要求零外部模型呼叫、連單一選取器定位都要完全寫死在本地的離線測試環境。
  • 為什麼:因為它在保留 Playwright 高速與確定性骨幹的同時,用三大原語補齊了跨版面自我修復與強型別擷取的最後一塊拼圖,讓瀏覽器自動化真正具備上線水準的可靠度。

如果你想持續追蹤更多開源 AI 開發工具、資安實戰與工程工作流拆解,歡迎免費訂閱 AI 郵報,每週精選最值得動手實測的技術情報送到你信箱。

資料來源