Stagehand：把瀏覽器自動化拆成 observe、act、extract 的可驗證 AI Agent SDK

如果你曾經把瀏覽器自動化接上大型語言模型，應該很快會遇到三個問題：頁面結構一改，原本的 selector 就失效；把整個 DOM 丟給模型，token 成本與延遲一起上升；還有最現實的安全疑慮——登入資訊、付款資料或其他敏感欄位，不應該因為要讓模型「看懂畫面」就直接送進模型。

我最近研究 browserbase/stagehand 時，覺得它值得被注意的地方，不只是「可以用自然語言操作瀏覽器」，而是它把瀏覽器 Agent 的核心互動拆成三個可以分別理解、測試與治理的動作：observe 用來找出可操作的目標，act 用來執行動作，extract 用來依 schema 擷取資料。這個拆分讓瀏覽器 Agent 不必是一個不可觀測的黑盒子，也讓開發者比較容易決定哪些步驟交給模型、哪些步驟仍然由程式控制。

本文以 Stagehand 官方 README、官方文件入口與 repository 內的 package metadata 為主，整理它的定位、實作模型、上手方式與限制。我的結論先講在前面：如果你的問題是「讓既有 Playwright 風格的瀏覽器流程多一層語意能力」，Stagehand 是一個很合理的研究與試作入口；但如果你需要完全可預測的高風險交易流程，仍然不應把每一個決策都交給自然語言代理。

Stagehand 解決的不是「沒有 API」

傳統瀏覽器自動化通常有兩種極端。

第一種是純 selector 驅動：開發者用 goto、click、locator、screenshot 等熟悉的瀏覽器 API 寫出完整流程。這種方式可預測、容易測試，但它依賴頁面結構。按鈕從 #submit 改成另一個 class，或表單的巢狀關係改變，測試就可能失效。

第二種是讓模型直接看頁面，再讓模型自行決定下一步。這種方式對介面變動比較有韌性，卻容易產生三種工程問題：模型拿到太多無關上下文、每一次動作難以重現，以及成功或失敗的原因不容易被觀測。

Stagehand 的定位比較像中間層。README 將它描述為 browser agents 的 SDK，同時保留 Playwright 風格的瀏覽器與元素 API。也就是說，你不需要把整個應用程式改寫成「只有 prompt 的自動化」；可以保留確定性的瀏覽器控制，再把真正需要語意理解的部分交給 observe、act 或 extract。

這個差異很重要。AI Agent 不一定要負責整個流程，才叫 Agent。比較成熟的做法，通常是把模型放在人類最擅長描述、但傳統 selector 不容易穩定表達的區段，例如「找到帳單表格中的所有發票」、「開啟帳務頁面」、「找出電子郵件輸入框」。而登入、權限、金額上限、最後送出等高風險步驟，仍然應該保留明確的程式邏輯與驗證。

三個核心動作：先理解，再操作，最後取回資料

1. `observe`：把自然語言轉成可執行目標

observe 的用途，是讓 Agent 根據頁面語意找出可以操作的元素。官方範例用它尋找電子郵件與密碼輸入框，回傳的是實際 selector 或可供後續操作使用的結果，而不是讓模型直接接觸完整憑證內容。

這裡的工程價值在於「找目標」與「填入資料」可以分開。你可以讓模型判斷哪一個欄位是 email，再由程式把真正的值填入；模型只需要知道元素位置，不必知道秘密本身。這個邊界不是自動完成的安全保證，但它提供了比「把整張畫面和所有欄位值一起送給模型」更好的設計方向。

2. `act`：用意圖描述操作，必要時重新計畫

act 接收像「click the sign in button」或「open the billing page」這類自然語言指令。Stagehand README 特別強調，當網站表單改版時，act 可以重新尋找執行動作的方法，這就是它所謂的 self-healing 方向。

但我不會把 self-healing 解讀成「永遠不會壞」。它比較接近「當頁面結構變動，但使用者意圖與視覺／語意線索仍然存在時，系統有機會重新對應操作」。如果按鈕文字改了、權限不足、頁面被導向 CAPTCHA，或新的流程需要額外的業務規則，Agent 仍然可能失敗。生產環境必須記錄每個 action 的輸入、候選元素、最後選擇與錯誤原因，並設計 timeout、重試上限和人工接管。

3. `extract`：把非結構化頁面變成 schema 驗證的資料

extract 是我認為最容易落地的部分。你可以用自然語言描述要擷取的資訊，再提供 schema，讓結果不是一段不可控的文字，而是可以被後續程式檢查的資料。

官方範例是從表格擷取所有發票，並回傳 schema-validated data。這使它適合用在研究助理、營運資料整理、後台報表匯出或跨網站的資料蒐集。不過 schema 驗證只能保證資料符合形狀，不能保證來源內容正確。金額、日期、幣別與權限狀態仍應做欄位級驗證，必要時保留原始頁面或截圖作為稽核證據。

一段可驗證的最小流程

Stagehand 官方 README 提供 TypeScript、Python 與 Go 的使用範例。以下示範 TypeScript 的概念，重點是保留「先觀察、再動作、最後擷取」的分層，而不是把所有事情塞進一個 prompt。

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

const browser = await localBrowser.launch({ userDataDir: "./browser-data" });
const stagehand = await Stagehand.create({ browser });

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

  const table = await stagehand.observe("find the invoice table");
  console.log("table target:", table);

  await stagehand.act("open the invoices section");

  const result = await stagehand.extract(
    "extract every invoice from the table",
    z.object({
      invoices: z.array(
        z.object({
          number: z.string(),
          date: z.string(),
          total: z.string(),
        }),
      ),
    }),
  );

  console.log(result.data.invoices);
} finally {
  await browser.close();
}

這段程式有幾個值得保留的界線。page.goto 是明確的程式操作；observe 與 act 處理需要理解介面的部分；extract 的輸出則經過 schema 轉換。實際導入時，我會再加上 URL allowlist、頁面來源檢查、敏感欄位遮罩、資料筆數上限與結果驗證。若流程會修改資料，還要把讀取與寫入分成不同權限，不能因為 Agent 能找到按鈕，就自動授予它修改帳務資料的權限。

如何開始：先跑本機，再決定是否使用雲端瀏覽器

目前 repository 的主 workspace 是 4.0.0，TypeScript SDK package metadata 顯示版本 4.1.0；Python SDK 也標示為 4.1.0。這提醒我們一件事：實際安裝前要以你要使用的 package registry 與 release 狀態為準，不要只看 repository 根目錄版本。

TypeScript 前置條件

官方 README 的本機範例以 Node.js 與 pnpm 為入口，workspace 的 engines 要求 Node.js 至少 22.18.0，並且本機執行需要安裝 Chrome。可以先建立一個乾淨目錄，再安裝 SDK：

pnpm add @browserbasehq/stagehand zod

接著用上面的最小範例驗證三件事：瀏覽器能否啟動、頁面能否載入、模型與 Stagehand 是否能完成一次 observe 或 extract。不要一開始就串接正式帳號；先用公開測試頁或本機 mock page，確認 log、timeout 與錯誤處理都能工作。

Python 與 Go 的選擇

如果團隊主要使用 Python，官方 package metadata 要求 Python 3.11 以上，安裝入口是：

python -m pip install stagehand

在本地開發環境中，我會優先使用專案自己的虛擬環境或 uv 管理依賴，避免污染系統 Python。Go SDK 則在 README 中以 github.com/browserbase/stagehand/packages/sdk-go/v4 為 import 路徑。三種語言的核心概念一致，但不要假設每個版本的 API 細節完全相同，應該以各 SDK 的官方 quickstart 與型別定義為準。

本機瀏覽器與 Browserbase

Stagehand 可以使用本機 browser，也可以指向 Browserbase 的 hosted browser。這兩條路徑的價值不同：本機適合開發與可控測試，雲端瀏覽器則比較適合需要遠端執行、工作階段管理、錄製與集中觀測的團隊。

README 也提到 Model Gateway、server-side caching、verified mode、residential proxies、persistent contexts 與 session recordings 等 Browserbase 能力。這些是服務整合與平台能力，不應直接算成 Stagehand SDK 本身的離線功能。導入前要分清楚：哪些能力在本機可用，哪些需要 Browserbase 帳戶、API key 或特定方案。

對 AI Chain 團隊最有價值的地方

一、把「瀏覽器 Agent」變成可拆解的 workflow

最值得借鑑的不是某一個 API 名稱，而是設計方式。當我們把流程拆成 observe、act、extract，就能為每一段設定不同的評估指標：

observe 評估找對元素的比例，以及是否誤選敏感欄位。
act 評估任務完成率、重試次數與平均延遲。
extract 評估 schema 通過率、欄位正確率與人工抽查結果。

這比只記錄「整個 Agent 成功或失敗」更有用。失敗發生時，我們可以知道是找不到元素、動作被拒絕，還是資料擷取後驗證失敗。

二、保留傳統自動化的逃生門

Stagehand 不是要求你放棄 Playwright 風格 API。這讓它比較適合漸進式導入：先把一個脆弱的 selector 區段換成 observe，再把某個資料表換成 schema-based extract，其餘流程維持原狀。當模型服務不可用時，也可以為關鍵路徑準備明確 selector 或人工審核 fallback。

三、同一套概念覆蓋多種語言

官方 README 同時展示 TypeScript、Python、Go 的 SDK 入口。對有不同服務團隊的組織來說，這降低了概念轉換成本。不過跨語言不代表跨環境零成本：瀏覽器生命週期、非同步模型、錯誤型別與套件版本仍要分別測試。

限制與我不建議的用法

第一，self-healing 不能取代測試。網站改版後，Agent 可能「做完了一件看似合理、其實不是原本任務」的事情。因此要對關鍵結果做 postcondition 檢查，例如確認 URL、頁面標題、資料筆數與欄位值，而不是只看沒有拋出例外。

第二，自然語言不是安全策略。若 Agent 能看到付款頁面，就可能在錯誤情境下理解錯誤金額或錯誤帳戶。所有不可逆操作都應該設計確認閘門，並限制模型可讀取和可操作的網域、路徑與元素。

第三，schema 驗證不是事實驗證。total 是字串且符合格式，不表示它真的等於頁面上的總額。涉及財務、醫療、法律或權限的資料，必須建立獨立的交叉驗證與人工覆核。

第四，雲端服務的能力與成本要獨立評估。Browserbase、Model Gateway、快取、錄製與代理等功能可能需要額外的帳戶與費用。不要把 README 中的雲端平台描述，誤當成安裝開源 SDK 後就自動擁有的功能。

第五，憑證管理必須先於 Agent。官方範例特別示範了 observe 找欄位，而不是把密碼交給模型；實際系統仍應使用環境變數、secret manager、最小權限帳戶與遮罩後的 log。任何「模型永遠不會看到秘密」的說法，都必須透過實際資料流與 telemetry 驗證，而不能只靠 API 名稱推論。

我會怎麼評估是否導入

如果要在團隊內做一週 proof of concept，我會採用以下順序。

第一天先建立沒有正式憑證的測試頁，記錄瀏覽器啟動、網路錯誤、模型請求與每一個 Stagehand 動作。第二天只測 extract，用固定 HTML 與固定 schema 建立基準資料。第三天加入 observe，比較 selector 版與語意版在頁面小幅改版後的差異。第四天才加入 act，並且只允許非破壞性操作。第五天注入錯誤：空頁面、權限不足、按鈕消失、網路逾時、重複提交，確認系統會停止而不是自動猜測。最後兩天再評估本機 Chrome 與雲端 browser 的成本、延遲、可觀測性與資料合規。

這個順序有一個好處：你不會因為一個成功的 demo，就直接相信整個 Agent workflow 已經適合生產。先把結果定義、失敗行為與資料邊界固定下來，再擴大自然語言操作的範圍。

結論：把模型放在最需要理解的地方

我認為 Stagehand 的核心價值，是把「瀏覽器自動化」重新整理成一個可組合的 Agent SDK，而不是單純替 selector 加上一層聊天介面。observe、act、extract 讓意圖理解、操作執行與資料輸出各自有清楚的責任邊界；Playwright 風格 API 則保留了傳統自動化的控制感。

它適合的團隊，是已經有瀏覽器流程，想逐步處理頁面變動、自然語言查詢或結構化擷取的人。它不適合被當成「只要給一句話，就能安全操作所有網站」的萬用代理。真正能不能落地，取決於你是否補上權限隔離、結果驗證、可觀測性、重試上限與人工接管。

如果你正在做研究助理、後台資料整理、跨網站查詢或瀏覽器型 coding agent，我會建議先從一個只讀、可重跑、可驗證的 extract workflow 開始，再逐步引入 observe 和 act。先讓模型幫你理解介面，再讓它在明確邊界內行動，通常比一開始就把整個瀏覽器交給它更可靠。

參考資料