MastraBrowser クラス

MastraBrowser クラスは、ブラウザ自動化 Provider の抽象基底クラスです。共通インターフェースには、ブラウザの起動とスレッドの分離に加え、スクリーンキャストのストリーミングと入力イベントが含まれます。

MastraBrowser を直接インスタンス化することはありません。代わりに、次の Provider 実装を使用します。

• AgentBrowser: refs を使用した決定論的なブラウザ自動化
• StagehandBrowser: 自然言語を使用した AI 駆動のブラウザ自動化
• BrowserViewer: CDP URL インジェクションを使用した 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,
})

コンストラクターパラメーター

headless?:

boolean

= true

ヘッドレスモード（表示 UI なし）でブラウザを実行するかどうか。

viewport?:

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

= { width: 1280, height: 720 }

ブラウザのビューポート寸法。ブラウザウィンドウのサイズを制御します。固定サイズではなく実際のブラウザウィンドウに合わせるには 'window' を設定します。これは agent-browser Provider、および CDP 経由で接続する場合の Stagehand でサポートされています。

timeout?:

number

デフォルトのタイムアウト（ミリ秒）。各 Provider が独自のセマンティクスとデフォルト値を定義します。詳細は各 Provider のリファレンスを参照してください。

cdpUrl?:

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

CDP WebSocket URL、HTTP エンドポイント、または同期／非同期の Provider 関数。指定すると、新しいブラウザを起動する代わりに既存のブラウザへ接続します。HTTP エンドポイントは内部で WebSocket に解決されます。scope: 'thread' とは併用できません（自動的に shared scope が使用されます）。

scope?:

'shared' | 'thread'

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

スレッド間におけるブラウザインスタンスのスコープ。'shared' では、すべてのスレッドが単一のブラウザインスタンスを共有します。'thread' では、各スレッドに専用のブラウザインスタンスが割り当てられます（完全分離）。

onLaunch?:

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

ブラウザが 'ready' ステータスに達した後に呼び出されるコールバック。

onClose?:

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

ブラウザが閉じられる前に呼び出されるコールバック。

screencast?:

ScreencastOptions

ブラウザフレームをストリーミングするための設定。

ScreencastOptions

format?:

'jpeg' | 'png'

スクリーンキャストフレームの画像形式。

quality?:

number

画像品質（1～100）。JPEG 形式にのみ適用されます。

maxWidth?:

number

スクリーンキャストフレームの最大幅。

maxHeight?:

number

スクリーンキャストフレームの最大高さ。

everyNthFrame?:

number

帯域幅を削減するため、N フレームごとにキャプチャします。

プロパティ

次のプロパティ（id、name、provider）は抽象プロパティであり、具象 Provider 実装で定義する必要があります。

id:

string

このブラウザインスタンスの一意な識別子。抽象プロパティであり、Provider によって定義されます。

name:

string

ブラウザ Provider の人が読める名前（例: 'AgentBrowser'、'StagehandBrowser'）。抽象プロパティであり、Provider によって定義されます。

provider:

string

Provider の識別子（例: 'vercel-labs/agent-browser'、'browserbase/stagehand'）。抽象プロパティであり、Provider によって定義されます。

headless:

boolean

ブラウザがヘッドレスモードで実行されているかどうか。

status:

BrowserStatus

現在のブラウザステータス: 'pending'、'launching'、'ready'、'error'、'closing'、または 'closed'。

メソッド

ライフサイクル

ensureReady()

ブラウザが起動済みで使用可能な状態であることを保証します。Tool の実行前に自動的に呼び出されます。基底クラスに実装されています。

await browser.ensureReady()

close()

ブラウザを閉じ、すべてのリソースを解放します。競合状態を安全に処理する形で基底クラスに実装されています。

await browser.close()

isBrowserRunning()

ブラウザが現在実行中かどうかを確認します。

const isRunning = browser.isBrowserRunning()

戻り値: boolean

スレッド管理

setCurrentThread(threadId)

ブラウザ操作に使用する現在のスレッド ID を設定します。Agent ランタイムが内部で使用します。

browser.setCurrentThread('thread-123')

getCurrentThread()

現在のスレッド ID を取得します。

const threadId = browser.getCurrentThread()

戻り値: string

hasThreadSession(threadId)

スレッドにアクティブなブラウザセッションがあるかどうかを確認します。

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

戻り値: boolean

closeThreadSession(threadId)

特定のスレッドのブラウザセッションを閉じます。'thread' scope では、そのスレッドのブラウザインスタンスを閉じます。'shared' scope では、スレッドの状態をクリアします。

await browser.closeThreadSession('thread-123')

Tool

getTools()

Agent で使用するブラウザ Tool を返します。各 Provider は、そのモデルに応じた異なる Tool を返します。

const tools = browser.getTools()

戻り値: Record<string, Tool>

スクリーンキャスト

startScreencast(options?, threadId?)

ブラウザフレームのストリーミングを開始します。フレームイベントを発行する 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>

入力インジェクション

injectMouseEvent(params, threadId?)

ブラウザにマウスイベントを注入します。Studio でのライブ操作に使用されます。

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

injectKeyboardEvent(params, threadId?)

ブラウザにキーボードイベントを注入します。Studio でのライブ操作に使用されます。

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

状態

getState(threadId?)

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>

ブラウザの scope

scope オプションは、会話スレッド間でブラウザインスタンスを共有する方法を制御します。

Scope	説明	ユースケース
'shared'	すべてのスレッドで単一のブラウザインスタンスを共有	競合しないタスクでコストを削減する場合
'thread'	スレッドごとに専用のブラウザインスタンスを使用	同時実行ユーザーを完全に分離する場合

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

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

cdpUrl を使用して外部ブラウザへ接続する場合、新しいブラウザインスタンスを生成できないため、scope は自動的に 'shared' へフォールバックします。

クラウドブラウザ 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 の概要: ブラウザ自動化の概念ガイド