BrowserViewer

BrowserViewer 類別為 CLI 型 Tool 提供瀏覽器自動化。它會透過 Playwright 啟動 Chrome，公開 Chrome DevTools Protocol（CDP）URL，並自動將其注入透過 Workspace Tool 執行的 CLI 指令。

當 Agent 透過 browser-use、agent-browser 或 browse 等 CLI Tool 操作瀏覽器時，請使用 BrowserViewer。以 SDK 為基礎的瀏覽器自動化請使用 AgentBrowser 或 StagehandBrowser。

使用範例

src/mastra/index.ts

import { Workspace, LocalSandbox } from '@mastra/core/workspace'
import { Memory } from '@mastra/memory'
import { BrowserViewer } from '@mastra/browser-viewer'
import { Agent } from '@mastra/core/agent'

const workspace = new Workspace({
  sandbox: new LocalSandbox({
    workingDirectory: './workspace',
  }),
  browser: new BrowserViewer({
    cli: 'browser-use',
    headless: false,
  }),
})

const browserAgent = new Agent({
  id: 'browser-agent',
  model: 'openai/gpt-5.6-sol',
  workspace,
  instructions: 'You are a web automation assistant.',
  memory: new Memory(),
})

連線至現有瀏覽器

const viewer = new BrowserViewer({
  cli: 'browser-use',
  cdpUrl: 'ws://127.0.0.1:9222/devtools/browser/abc123',
})

提供 cdpUrl 時，BrowserViewer 會連線至現有瀏覽器，而不是啟動新瀏覽器。scope 預設為 'shared'。

Constructor 參數

cli:

'agent-browser' | 'browser-use' | 'browse' | 'browse-cli'

Agent 用於瀏覽器自動化的 CLI。CLI 會透過 CDP URL 連線至 Chrome。

headless?:

boolean

= true

是否以 headless 模式執行 Chrome。

cdpUrl?:

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

用於連線至現有瀏覽器，而不啟動新瀏覽器的 CDP WebSocket URL。

cdpPort?:

number

= 0 (auto-assign)

Chrome 遠端偵錯連接埠。只在啟動 Chrome 時使用（透過 cdpUrl 連線時不使用）。

scope?:

'shared' | 'thread'

= 'thread'

瀏覽器 instance scope。thread 讓每個 thread 使用自己的瀏覽器；shared 讓所有 thread 共用一個瀏覽器。提供 cdpUrl 時預設為 shared。

viewport?:

{ width: number; height: number }

= { width: 1280, height: 720 }

瀏覽器 viewport 尺寸。

executablePath?:

string

Chrome 可執行檔的路徑。預設使用 Playwright bundle 內的 Chromium。

onLaunch?:

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

瀏覽器準備就緒後呼叫的 callback。

onClose?:

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

瀏覽器關閉前呼叫的 callback。

screencast?:

ScreencastOptions

將瀏覽器 frame 串流至 Studio 的設定。

屬性

id:

string

此瀏覽器 instance 的不重複識別碼，格式為 'browser-viewer-{timestamp}'。

name:

string

'BrowserViewer'

provider:

string

'browser-viewer'

providerType:

'cli'

一律為 'cli'，用於區分 BrowserViewer 與 AgentBrowser 等 SDK 型 Provider。

cli:

'agent-browser' | 'browser-use' | 'browse' | 'browse-cli'

此 instance 設定使用的 CLI Provider。

status:

BrowserStatus

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

方法

生命週期

launch(threadId?)

啟動 Chrome。使用 'shared' scope 時會啟動單一共用瀏覽器；使用 'thread' scope 時，會為指定 thread 啟動瀏覽器。

await viewer.launch()
await viewer.launch('thread-123')

ensureReady()

確保瀏覽器已啟動並準備就緒。使用 'thread' scope 時，會視需要為目前 thread 建立新瀏覽器。

await viewer.ensureReady()

isBrowserRunning(threadId?)

檢查瀏覽器是否正在執行。使用 'thread' scope 時，會檢查指定 thread。

const running = viewer.isBrowserRunning()
const threadRunning = viewer.isBrowserRunning('thread-123')

傳回：boolean

close()

關閉所有瀏覽器 instance 並清理資源。

await viewer.close()

CDP 存取

getCdpUrl(threadId?)

傳回目前或指定 thread 的 CDP WebSocket URL。CLI Tool 使用此 URL 連線至受管理的瀏覽器。

const cdpUrl = viewer.getCdpUrl()
// => 'ws://127.0.0.1:52481/devtools/browser/abc...'

傳回：string | null

connectToExternalCdp(cdpUrl, threadId?)

透過 CDP URL 連線至外部瀏覽器，以進行 screencast。Agent 提供自己的瀏覽器 endpoint（例如雲端瀏覽器服務）時請使用此方法。BrowserViewer 會連線以進行 screencast，但不管理瀏覽器生命週期。

await viewer.connectToExternalCdp('wss://cloud.example.com/session', 'thread-123')

Screencast

startScreencast(options?)

開始串流瀏覽器 frame。傳回會發出 frame event 的 ScreencastStream。分頁切換時會建立新的 CDP session，自動處理切換。

const stream = await viewer.startScreencast({
  format: 'jpeg',
  quality: 80,
})

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?)

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

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

injectKeyboardEvent(params, threadId?)

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

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

支援的 CLI

每個 CLI 都必須分別安裝，也都會發布 Skill，教導 Agent 使用其指令與 Workflow。CLI 指令透過 workspace_execute_command 執行時，Mastra 會偵測並使用正確的 flag，自動注入 CDP URL。

與 SDK Provider 不同，BrowserViewer 不提供 Agent Tool。Agent 會改用透過 workspace_execute_command 執行的 CLI 指令。

agent-browser

設定值：'agent-browser' · CDP flag：--cdp

npm install -g agent-browser
npx skills add vercel-labs/agent-browser

browser-use

設定值：'browser-use' · CDP flag：--cdp-url

pip install browser-use
npx skills add browser-use/browser-use --skill browser-use

browse（指令：browse）

設定值：'browse' · CDP flag：--ws

npm install -g browse
browse skills install

相關內容

• BrowserViewer 指南：設定與使用教學
• MastraBrowser：基底類別 API 參考文件
• Workspace 概觀：Workspace 設定