Browser Use Python 入門：做一個只讀 Agent

用 Python 建立 Browser Use Agent，先把模型、獨立的 Browser 工作階段，以及答案可查證的任務交給 Agent。這個範例從本機網頁讀取標題和編號。Pydantic 檢查資料格式，程式再比對兩個欄位的值。

有使用者在 GitHub 回報動作驗證失敗，舊版程式因為模型生成的瀏覽器動作未通過檢查而中斷。下文依開源快速入門和輸出格式文件撰寫。程式介面已對照文件，範例未做端對端執行。

重點

• 要自行控制瀏覽器工作階段、任務和驗證，可採用 Browser Use Python 函式庫。

• 第一個任務使用本機 HTML，以及未登入任何帳號的瀏覽器工作階段。

• 瀏覽器與模型分開選擇。ChatBrowserUse 會呼叫託管模型，即使 Chromium 在本機執行。

• history.is_successful() 記錄 Agent 自行判定的狀態。用伺服器紀錄和實際欄位另行核對。

• 測試頁只放已知文字，省去表單、上傳和帳號。

決定瀏覽器和模型在哪裡執行

模型選擇動作，瀏覽器開啟網頁並執行動作，Python 程式把兩者接起來。先判斷是否需要瀏覽器 Agent、固定的 Playwright 腳本，或網頁搜尋就能完成工作。

範例採第一種做法。依快速入門將 BROWSER_USE_API_KEY 放在環境變數或本機 .env，避免將金鑰提交到版本庫。在安裝了 uv 的新專案目錄執行下列指令。

uv init --python 3.12
uv add browser-use
uvx browser-use install

安裝步驟會準備 Chromium。若需要重建環境，保留鎖定檔。支援模型文件列出 ChatOllama 等配接器。更換模型時沿用同一個測試頁和預期值，同時檢查動作與輸出。Cloud 快速入門另有驗證和工作階段設定。

有位 Reddit 上的測試人員 希望用自架模型將客戶資料留在內部環境。如果有相同要求，可另選本機模型。本例只把虛構測試資料交給模型。

準備一個答案已知的測試頁

將 HTML 存為 fixture/index.html。頁面只含測試文字和虛構編號。另開終端機執行 HTTP 伺服器，它只提供 fixture 目錄的內容。

<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>Inventory fixture</title>
<main>
  <h1>Inventory Check</h1>
  <p>Reference code: BU-741</p>
</main>
</html>

uv run python -m http.server 8765 --bind 127.0.0.1 --directory fixture

127.0.0.1 指向瀏覽器所在的電腦。遠端瀏覽器會讀自己的本機位址。此處讓瀏覽器和伺服器在同一台電腦執行，必要時先手動開啟測試頁。

執行 Agent 並核對兩個欄位

在專案根目錄儲存 check_page.py。Browser 參數文件說明網域限制，Agent 參數文件說明輸出格式設定。任務只提供網址，預期字串留在驗證程式裡，讓模型從頁面取得答案。

import asyncio
from tempfile import TemporaryDirectory

from browser_use import Agent, Browser, ChatBrowserUse
from pydantic import BaseModel

URL = "http://127.0.0.1:8765/"


class PageCheck(BaseModel):
    heading: str
    reference: str


async def main():
    with TemporaryDirectory(prefix="browser-use-fixture-") as profile:
        browser = Browser(
            headless=True,
            user_data_dir=profile,
            allowed_domains=["127.0.0.1"],
            accept_downloads=False,
        )
        try:
            agent = Agent(
                task=(
                    f"Open {URL} and read its visible heading and reference code. "
                    "Return only those two values. Do not interact with any form."
                ),
                browser=browser,
                llm=ChatBrowserUse(),
                output_model_schema=PageCheck,
            )
            history = await agent.run(max_steps=5)
            result = history.structured_output
            expected = PageCheck(heading="Inventory Check", reference="BU-741")
            if result != expected:
                raise RuntimeError("The output does not match the fixture.")
            print(result.model_dump_json())
        finally:
            await browser.stop()


if __name__ == "__main__":
    asyncio.run(main())

uv run python check_page.py

預期標題是 Inventory Check，編號是 BU-741。這是頁面事先寫好的資料。如果腳本報錯，先看歷史紀錄。增加步數可能只會重複失敗的動作。

分開確認頁面請求、輸出和副作用

先確認伺服器在本次執行期間收到對 / 的請求，再檢查 history.urls()、history.errors() 和輸出。輸出格式文件將任務結束、Agent 自行判定成功與獨立驗證分開說明。

使用獨立工作階段可以隔離平時登入的帳號。連接既有瀏覽器會改變 Agent 能讀到的工作階段和 Cookie。網域允許清單限制的是導覽。接入真實應用時，在伺服器強制執行唯讀權限，並使用測試帳號。詳見瀏覽器 Agent 的安全風險。

從第一個出錯的環節查起

另一則遠端 CDP 問題描述瀏覽器協定呼叫停住的情況。這與模型動作驗證是不同階段的問題。兩則回報都有各自的版本和環境，排查時要看自己的紀錄。

如果任務可能建立資料或發送訊息，逾時後先到目標系統查明是否執行，再決定要不要重試。本例的測試頁可重複讀取並比對請求紀錄。

何時適合保留 Python 整合

下游程式需要接收並驗證欄位時，採用 Python 整合。網址、選擇器和順序都固定時，可直接使用瀏覽器腳本。只想核對一次頁面文字，手動打開測試頁就夠了。Tabbit 與 Browser Use 的比較和 Agentic Browser 指南說明瀏覽器介面與程式整合的差異。

第一次執行時，確認頁面真的收到請求，而且兩個欄位都符合預期。之後更換瀏覽器、模型或目標頁面時，一次改一項再重新檢查。

Secholar.L

Tabbit 成長與內容

Secholar.L 專注 AI 瀏覽器與 Agent 工作流的實測寫作,基於真實調研比較工具,引用可查證的一手來源。