BrowserViewer

BrowserViewer クラスは、CLI ベースの Tool にブラウザー自動化機能を提供します。Playwright で Chrome を起動して Chrome DevTools Protocol（CDP）URL を公開し、Workspace Tool から実行される CLI コマンドにその URL を自動的に挿入します。

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

Chrome をヘッドレスモードで実行するかどうか。

cdpUrl?:

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

新しいブラウザーを起動せず、既存のブラウザーに接続するための CDP WebSocket URL。

cdpPort?:

number

= 0 (auto-assign)

Chrome のリモートデバッグ用ポート。Chrome を起動する場合にのみ使用されます（cdpUrl 経由で接続する場合は使用されません）。

scope?:

'shared' | 'thread'

= 'thread'

ブラウザーインスタンスの scope。'thread' では各スレッドに専用のブラウザーを割り当てます。'shared' では1つのブラウザーをすべてのスレッドで共有します。cdpUrl を指定した場合のデフォルトは 'shared' です。

viewport?:

{ width: number; height: number }

= { width: 1280, height: 720 }

ブラウザーのビューポートサイズ。

executablePath?:

string

Chrome 実行ファイルへのパス。デフォルトでは Playwright にバンドルされた Chromium を使用します。

onLaunch?:

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

ブラウザーの準備が完了した後に呼び出されるコールバック。

onClose?:

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

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

screencast?:

ScreencastOptions

ブラウザーのフレームを 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' の場合、共有ブラウザーを1つ起動します。scope が 'thread' の場合、指定したスレッド用のブラウザーを起動します。

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

ensureReady()

ブラウザーが起動済みで、使用できる状態であることを保証します。scope が 'thread' の場合、必要に応じて現在のスレッド用に新しいブラウザーを作成します。

await viewer.ensureReady()

isBrowserRunning(threadId?)

ブラウザーが実行中かどうかを確認します。scope が 'thread' の場合、指定したスレッドを確認します。

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

戻り値: boolean

close()

すべてのブラウザーインスタンスを閉じ、リソースをクリーンアップします。

await viewer.close()

CDP へのアクセス

getCdpUrl(threadId?)

現在のスレッドまたは指定したスレッドの 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 を介して外部ブラウザーに接続します。Agent が独自のブラウザーエンドポイント（クラウドブラウザーサービスなど）を提供する場合に使用します。BrowserViewer はブラウザーのライフサイクルを管理せず、スクリーンキャストのために接続します。

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

スクリーンキャスト

startScreencast(options?)

ブラウザーフレームのストリーミングを開始します。フレームイベントを発行する ScreencastStream を返します。タブが切り替わると新しい CDP セッションを作成し、タブの切り替えを自動的に処理します。

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 は個別にインストールする必要があります。また、それぞれの CLI は、コマンドとワークフローを Agent に教える Skill も公開しています。CLI コマンドが workspace_execute_command を通じて実行されると、Mastra がそのコマンドを検出し、適切なフラグを使用して CDP URL を自動的に挿入します。

SDK Provider とは異なり、BrowserViewer は Agent Tool を提供しません。代わりに、Agent は workspace_execute_command を通じて CLI コマンドを使用します。

agent-browser

設定値: 'agent-browser' · CDP フラグ: --cdp

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

browser-use

設定値: 'browser-use' · CDP フラグ: --cdp-url

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

browse（コマンド: browse）

設定値: 'browse' · CDP フラグ: --ws

npm install -g browse
browse skills install

関連項目

• BrowserViewer ガイド: セットアップと使用方法のチュートリアル
• MastraBrowser: 基底クラスの API リファレンス
• Workspace の概要: Workspace の設定