MastraBrowser 類別

MastraBrowser 類別是瀏覽器自動化 Provider 的抽象基底類別。其共用 interface 涵蓋瀏覽器啟動與 thread 隔離，以及 screencast 串流與輸入 event。

請勿直接建立 MastraBrowser instance，改用 Provider 實作：

• AgentBrowser：使用 ref 的確定性瀏覽器自動化
• StagehandBrowser：使用自然語言的 AI 驅動瀏覽器自動化
• BrowserViewer：透過 CDP URL injection 操作的 CLI 型瀏覽器自動化

使用範例

src/mastra/agents/index.ts

import { Agent } from '@mastra/core/agent'
import { AgentBrowser } from '@mastra/agent-browser'

const browser = new AgentBrowser({
  headless: true,
  viewport: { width: 1280, height: 720 },
  scope: 'thread',
})

export const browserAgent = new Agent({
  id: 'browser-agent',
  name: 'Browser Agent',
  instructions: 'You can browse the web to find information.',
  model: 'openai/gpt-5.6-sol',
  browser,
})

Constructor 參數

headless?:

boolean

= true

是否以 headless 模式執行瀏覽器（不顯示 UI）。

viewport?:

{ width: number; height: number } | 'window'

= { width: 1280, height: 720 }

瀏覽器 viewport 尺寸，用於控制瀏覽器視窗大小。設為 window 可符合實際瀏覽器視窗，而不使用固定尺寸；agent-browser Provider 以及透過 CDP 連線的 Stagehand 支援此設定。

timeout?:

number

預設逾時毫秒數。各 Provider 會定義自己的語意與預設值，詳情請參閱 Provider 參考文件。

cdpUrl?:

string | (() => string | Promise<string>)

CDP WebSocket URL、HTTP endpoint，或同步／非同步 Provider 函式。提供時會連線至現有瀏覽器，而不是啟動新瀏覽器。HTTP endpoint 會在內部解析為 WebSocket。不能與 scope: 'thread' 一起使用（會自動使用 shared scope）。

scope?:

'shared' | 'thread'

= 'thread' (or 'shared' when cdpUrl is provided)

瀏覽器 instance 跨 thread 的範圍。shared 表示所有 thread 共用一個瀏覽器 instance；thread 表示每個 thread 都有自己的瀏覽器 instance（完全隔離）。

onLaunch?:

(args: { browser: MastraBrowser }) => void | Promise<void>

瀏覽器進入 'ready' 狀態後呼叫的 callback。

onClose?:

(args: { browser: MastraBrowser }) => void | Promise<void>

瀏覽器關閉前呼叫的 callback。

screencast?:

ScreencastOptions

瀏覽器 frame 串流設定。

ScreencastOptions

format?:

'jpeg' | 'png'

screencast frame 的圖片格式。

quality?:

number

圖片品質（1 至 100），只適用於 JPEG 格式。

maxWidth?:

number

screencast frame 的最大寬度。

maxHeight?:

number

screencast frame 的最大高度。

everyNthFrame?:

number

每 N 個 frame 擷取一次，以降低頻寬。

屬性

以下屬性（id、name、provider）為 abstract，必須由具體 Provider 實作定義：

id:

string

此瀏覽器 instance 的不重複識別碼。abstract，由 Provider 定義。

name:

string

方便閱讀的瀏覽器 Provider 名稱，例如 'AgentBrowser'、'StagehandBrowser'。abstract，由 Provider 定義。

provider:

string

Provider 識別碼，例如 'vercel-labs/agent-browser'、'browserbase/stagehand'。abstract，由 Provider 定義。

headless:

boolean

瀏覽器是否以 headless 模式執行。

status:

BrowserStatus

目前瀏覽器狀態：'pending'、'launching'、'ready'、'error'、'closing' 或 'closed'。

方法

生命週期

ensureReady()

確保瀏覽器已啟動並可供使用。在 Tool 執行前自動呼叫。實作位於基底類別。

await browser.ensureReady()

close()

關閉瀏覽器並清理所有資源。實作位於基底類別，且能安全處理 race condition。

await browser.close()

isBrowserRunning()

檢查瀏覽器目前是否正在執行。

const isRunning = browser.isBrowserRunning()

傳回： boolean

Thread 管理

setCurrentThread(threadId)

設定瀏覽器操作目前使用的 thread ID。由 Agent runtime 內部使用。

browser.setCurrentThread('thread-123')

getCurrentThread()

取得目前的 thread ID。

const threadId = browser.getCurrentThread()

傳回： string

hasThreadSession(threadId)

檢查 thread 是否具有有效的瀏覽器 session。

const hasSession = browser.hasThreadSession('thread-123')

傳回： boolean

closeThreadSession(threadId)

關閉特定 thread 的瀏覽器 session。使用 'thread' scope 時，會關閉該 thread 的瀏覽器 instance；使用 'shared' scope 時，會清除 thread state。

await browser.closeThreadSession('thread-123')

Tool

getTools()

傳回供 Agent 使用的瀏覽器 Tool。各 Provider 會依模型傳回不同 Tool。

const tools = browser.getTools()

傳回： Record<string, Tool>

Screencast

startScreencast(options?, threadId?)

開始串流瀏覽器 frame。傳回會發出 frame event 的 ScreencastStream。

const stream = await browser.startScreencast({ format: 'jpeg', quality: 80 }, 'thread-123')

stream.on('frame', frame => {
  console.log('Frame received:', frame.data.length, 'bytes')
})

stream.on('stop', reason => {
  console.log('Screencast stopped:', reason)
})

傳回： Promise<ScreencastStream>

輸入 injection

injectMouseEvent(params, threadId?)

將滑鼠 event 注入瀏覽器。Studio 使用此方法進行即時互動。

await browser.injectMouseEvent({
  type: 'mousePressed',
  x: 100,
  y: 200,
  button: 'left',
  clickCount: 1,
})

injectKeyboardEvent(params, threadId?)

將鍵盤 event 注入瀏覽器。Studio 使用此方法進行即時互動。

await browser.injectKeyboardEvent({
  type: 'keyDown',
  key: 'Enter',
  code: 'Enter',
})

State

getState(threadId?)

取得目前的瀏覽器 state，包括 URL 與分頁。

const state = await browser.getState('thread-123')
console.log('Current URL:', state.currentUrl)
console.log('Tabs:', state.tabs)

傳回： Promise<BrowserState>

interface BrowserState {
  currentUrl: string | null
  tabs: BrowserTabState[]
  activeTabIndex: number
}

interface BrowserTabState {
  id: string
  url: string
  title: string
}

getCurrentUrl(threadId?)

取得目前頁面 URL。

const url = await browser.getCurrentUrl()

傳回： Promise<string | null>

Browser scope

scope 選項控制瀏覽器 instance 在對話 thread 之間的共用方式：

Scope	說明	使用情境
'shared'	所有 thread 共用單一瀏覽器 instance	適用於不互相衝突的任務，可節省成本
'thread'	每個 thread 都有自己的瀏覽器 instance	為並行使用者提供完整隔離

// Shared browser for all threads
const sharedBrowser = new AgentBrowser({
  scope: 'shared',
})

// Isolated browser per thread
const isolatedBrowser = new AgentBrowser({
  scope: 'thread',
})

使用 cdpUrl 連線至外部瀏覽器時，scope 會自動改用 'shared'，因為無法建立新的瀏覽器 instance。

雲端瀏覽器 Provider

使用 cdpUrl 選項連線至雲端瀏覽器服務：

// Static CDP URL
const browser = new AgentBrowser({
  cdpUrl: 'wss://browser.example.com/ws',
})

// Dynamic CDP URL (e.g., session-based)
const browser = new AgentBrowser({
  cdpUrl: async () => {
    const session = await createBrowserSession()
    return session.wsUrl
  },
})

相關內容

• AgentBrowser：確定性瀏覽器自動化
• StagehandBrowser：AI 驅動的瀏覽器自動化
• Browser 概觀：瀏覽器自動化概念指南