BrowserViewer

BrowserViewer 類別為以 CLI 為基礎的 Tool 提供瀏覽器自動化功能。它會透過 Playwright 啟動 Chrome、提供 Chrome DevTools Protocol（CDP）URL，並自動將該 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'。

建構函式參數

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'

瀏覽器實例的 scope。'thread' 會為每個 thread 提供獨立的瀏覽器；'shared' 則讓所有 thread 共用同一個瀏覽器。提供 cdpUrl 時，預設為 'shared'。

viewport?:

{ width: number; height: number }

= { width: 1280, height: 720 }

瀏覽器 viewport 的尺寸。

executablePath?:

string

Chrome 執行檔的路徑。預設使用 Playwright 隨附的 Chromium。

onLaunch?:

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

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

onClose?:

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

瀏覽器關閉前呼叫的 callback。

screencast?:

ScreencastOptions

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

屬性

id:

string

此瀏覽器實例的唯一識別碼，會產生為 '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'

此實例設定使用的 CLI Provider。

status:

BrowserStatus

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

方法

生命週期

launch(threadId?)

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

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

ensureReady()

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

await viewer.ensureReady()

isBrowserRunning(threadId?)

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

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

傳回：boolean

close()

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

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 事件的 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>

注入輸入事件

injectMouseEvent(params, threadId?)

透過 CDP 將滑鼠事件注入瀏覽器，供 Studio 即時互動使用。

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

injectKeyboardEvent(params, threadId?)

透過 CDP 將鍵盤事件注入瀏覽器，供 Studio 即時互動使用。

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

支援的 CLI

每個 CLI 都必須分別安裝，並各自發佈一個 Skill，讓 Agent 學會相關指令和 Workflow。透過 workspace_execute_command 執行 CLI 指令時，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 設定