BrowserUse - AgentBay

什麼是 AgentBay AIBrowser

Agentbay AIBrowser 是一個可擴充的託管平台，用於大規模運行無頭/有頭瀏覽器。提供基礎設施進行建立和管理會話、初始化瀏覽器執行個體，並按需分配底層硬體資源。專為網頁自動化情境設計，如表單填寫、類比使用者操作，以及在現代動態網站上編排複雜的多步驟任務。

Agentbay AIBrowser API 提供了簡潔的介面來控制瀏覽器，以及實用的工具來建立並管理會話，通過先進的 AI 能力來執行自然語言描述的任務。

主要特點

自動化架構相容性：通過 CDP 高度相容 Playwright 和 Puppeteer。
安全可擴充的基礎架構：託管式會話、隔離環境和彈性資源分派。
可觀測性：會話回放、會話檢查器和即時模式，支援Just-in-Time 偵錯。
進階能力：上下文管理、IP 代理和隱藏/指紋選項。
AI 驅動的 PageUseAgent：通過自然語言執行複雜 Web 工作流程工作。
豐富的API介面：提供簡潔的會話管理、瀏覽器生命週期控制和代理操作介面。

快速入門（Python）

以下是一個最小化的可運行樣本，展示了如何通過 AgentBay Python SDK 初始化瀏覽器並使用 Playwright 通過 CDP 進行驅動。範例程式碼將完成以下操作：

通過使用的 API 金鑰構建 AgentBay 用戶端進行身分識別驗證，構建可信通道。
通過建立帶有瀏覽器啟用鏡像的會話來配置一個新的執行環境，確保所需的運行時可用。
使用 BrowserOption() 初始化會話的瀏覽器，啟動一個準備自動化的遠程瀏覽器執行個體。
通過 get_endpoint_url() 擷取 CDP 終端 URL，並使用 Playwright 的 connect_over_cdp 進行串連，將本地代碼橋接到遠程瀏覽器。
建立活動串連後，代碼將開啟新頁面並導航至網站，可以像本地瀏覽器一樣檢查或操作 DOM。
當所有工作完成後，刪除會話以釋放已指派的資源。

先決條件：

設定 API 金鑰：export AGENTBAY_API_KEY=your_api_key
安裝依賴項：pip install wuying-agentbay-sdk playwright
安裝 Playwright 瀏覽器：python -m playwright install chromium

import os
import asyncio
from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams
from agentbay.browser.browser import BrowserOption
from playwright.async_api import async_playwright

async def main():
    api_key = os.getenv("AGENTBAY_API_KEY")
    if not api_key:
        raise RuntimeError("AGENTBAY_API_KEY environment variable not set")

    agent_bay = AgentBay(api_key=api_key)

    # Create a session (use an image with browser preinstalled)
    params = CreateSessionParams(image_id="browser_latest")
    session_result = agent_bay.create(params)
    if not session_result.success:
        raise RuntimeError(f"Failed to create session: {session_result.error_message}")

    session = session_result.session

    # Initialize browser (supports stealth, proxy, fingerprint, etc. via BrowserOption)
    ok = await session.browser.initialize_async(BrowserOption())
    if not ok:
        raise RuntimeError("Browser initialization failed")

    endpoint_url = session.browser.get_endpoint_url()

    # Connect Playwright over CDP and automate
    async with async_playwright() as p:
        browser = await p.chromium.connect_over_cdp(endpoint_url)
        page = await browser.new_page()
        await page.goto("https://www.aliyun.com")
        print("Title:", await page.title())
        await browser.close()

    session.delete()

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

關鍵的瀏覽器 API：

Browser.initialize(option: BrowserOption) -> bool / initialize_async(...)：為會話啟動瀏覽器執行個體。
Browser.get_endpoint_url() -> str：返回 CDP WebSocket 終端；與 Playwright connect_over_cdp 一起使用。
Browser.is_initialized() -> bool：檢查瀏覽器是否就緒。

基本配置

有時網頁需要不同的配置和顯示環境。通過自訂瀏覽器的身份標識和視窗尺寸，可以引導網站展現出針對特定裝置類別或受眾群體的體驗。以下樣本將設定自訂使用者代理程式和精確的視窗尺寸，將完成以下操作：

進行身分識別驗證並建立一個託管瀏覽器的會話。
類比一個常見的 macOS + Chrome 瀏覽器的 User-Agent，用於標識瀏覽器環境。
使用 initialize_async 啟動瀏覽器，請求 CDP 終端，並通過 Playwright 建立串連。
訪問網站並驗證User-Agent和視窗大小是否被正確設定。

import os
import asyncio
from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams
from agentbay.browser.browser import BrowserOption, BrowserViewport
from playwright.async_api import async_playwright

CUSTOM_UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36"

async def main():
    agent_bay = AgentBay(api_key=os.environ["AGENTBAY_API_KEY"])  # first, authenticate

    params = CreateSessionParams(image_id="browser_latest")       # then, provision a browser-ready session
    result = agent_bay.create(params)
    if not result.success:
        raise RuntimeError(result.error_message)

    session = result.session

    # after that, define how the browser should look and feel
    option = BrowserOption(
        user_agent=CUSTOM_UA,                    # present ourselves with a custom identity
        viewport=BrowserViewport(width=1366, height=768),  # and stand on a stage sized like a common laptop
    )

    ok = await session.browser.initialize_async(option)
    if not ok:
        raise RuntimeError("Browser initialization failed")

    endpoint_url = session.browser.get_endpoint_url()      # now, discover the CDP doorway

    async with async_playwright() as p:
        browser = await p.chromium.connect_over_cdp(endpoint_url)  # step through and take control
        page = await browser.new_page()

        await page.goto("https://www.whatismybrowser.com/detect/what-is-my-user-agent")
        # verify our new voice and our new stage
        ua = await page.evaluate("navigator.userAgent")
        w = await page.evaluate("window.innerWidth")
        h = await page.evaluate("window.innerHeight")
        print("Effective UA:", ua)
        print("Viewport:", w, "x", h)

        await browser.close()

    session.delete()  # finally, bow out and free the stage

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

使用 PageUseAgent【Beta】

PageUseAgent 使使用者能夠使用自然語言與瀏覽器對話，並驅使瀏覽器執行使用者意圖。PageUseAgent調用依賴大語言模型能力，將產生token消耗，按照後付費規則產生費用，Beta版試用期間免費試用。

以下樣本將在 Google 搜尋一本書，將完成以下操作：

建立並初始化一個瀏覽器會話，並告知 Agent 需要做什麼。
輸入查詢內容，代理會將意圖轉化為頁面操作。
瀏覽器自動在搜尋方塊輸入查詢內容並跳轉至結果頁面。
關閉瀏覽器並釋放會話。

import os
import asyncio
from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams
from agentbay.browser.browser import BrowserOption
from agentbay.browser.browser_agent import ActOptions
from playwright.async_api import async_playwright

BOOK_QUERY = "The Pragmatic Programmer"

async def main():
    agent_bay = AgentBay(api_key=os.environ["AGENTBAY_API_KEY"])  # authenticate

    params = CreateSessionParams(image_id="browser_latest")       # provision session with browser image
    result = agent_bay.create(params)
    if not result.success:
        raise RuntimeError(result.error_message)
    session = result.session

    # initialize the remote browser
    if not await session.browser.initialize_async(BrowserOption()):
        raise RuntimeError("Browser initialization failed")

    endpoint_url = session.browser.get_endpoint_url()

    async with async_playwright() as p:
        browser = await p.chromium.connect_over_cdp(endpoint_url)
        page = await browser.new_page()

        # step onto the stage
        await page.goto("https://www.google.com")

        # ask the agent to act: type the book name into the search box
        act_result = await session.browser.agent.act_async(ActOptions(
            action=f"Type '{BOOK_QUERY}' into the search box and submit",
        ), page)
        print("act_result:", act_result.success, act_result.message)

        # let the agent open the first result
        open_first = await session.browser.agent.act_async(ActOptions(
            action="Click the first result in the search results",
        ), page)
        print("open_first:", open_first.success, open_first.message)

        # pause briefly to observe
        await page.wait_for_timeout(5000)
        await browser.close()

    session.delete()

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

關於PageUseAgent.act：

variables插值動態值，實現可複用的提示。
通過對底層擷取其 context_id 和 page_id 在活動 Playwright 頁面上操作。
返回結構化的 ActResult，包含 success和message，便於日誌記錄和恢複流程。

限制

PageUseAgent不包括長期規劃器，不會自行編排多步驟計劃。依賴於調用者（或更進階別的代理）將專案分解為步驟，並為每個步驟調用 act 或其他 PageUseAgent 方法。

PageUseAgent優勢在於精確、原子的網頁操作（點擊、填充、滾動等）並快速一致地執行。

PageUseAgent優先考慮每一步的輸送量和準確性，並將複雜的任務規劃和分支邏輯留給外部控制器。