> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt

# 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`](https://mastra.zisheng.pro/ja/reference/browser/agent-browser) または [`StagehandBrowser`](https://mastra.zisheng.pro/ja/reference/browser/stagehand-browser) を使用してください。

## 使用例

```typescript
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(),
})
```

### 既存のブラウザーへの接続

```typescript
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`): Chrome をヘッドレスモードで実行するかどうか。 (Default: `true`)

**cdpUrl** (`string | (() => string | Promise<string>)`): 新しいブラウザーを起動せず、既存のブラウザーに接続するための CDP WebSocket URL。

**cdpPort** (`number`): Chrome のリモートデバッグ用ポート。Chrome を起動する場合にのみ使用されます（cdpUrl 経由で接続する場合は使用されません）。 (Default: `0 (auto-assign)`)

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

**viewport** (`{ width: number; height: number }`): ブラウザーのビューポートサイズ。 (Default: `{ 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'` の場合、指定したスレッド用のブラウザーを起動します。

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

#### `ensureReady()`

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

```typescript
await viewer.ensureReady()
```

#### `isBrowserRunning(threadId?)`

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

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

戻り値: `boolean`

#### `close()`

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

```typescript
await viewer.close()
```

### CDP へのアクセス

#### `getCdpUrl(threadId?)`

現在のスレッドまたは指定したスレッドの CDP WebSocket URL を返します。CLI Tool はこの URL を使用して、管理対象のブラウザーに接続します。

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

戻り値: `string | null`

#### `connectToExternalCdp(cdpUrl, threadId?)`

スクリーンキャスト用に、CDP URL を介して外部ブラウザーに接続します。Agent が独自のブラウザーエンドポイント（クラウドブラウザーサービスなど）を提供する場合に使用します。BrowserViewer はブラウザーのライフサイクルを管理せず、スクリーンキャストのために接続します。

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

### スクリーンキャスト

#### `startScreencast(options?)`

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

```typescript
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 でのライブ操作に使用されます。

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

#### `injectKeyboardEvent(params, threadId?)`

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

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

## 対応している CLI

各 CLI は個別にインストールする必要があります。また、それぞれの CLI は、コマンドとワークフローを Agent に教える [Skill](https://mastra.zisheng.pro/ja/docs/workspace/skills) も公開しています。CLI コマンドが `workspace_execute_command` を通じて実行されると、Mastra がそのコマンドを検出し、適切なフラグを使用して CDP URL を自動的に挿入します。

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

### [`agent-browser`](https://www.npmjs.com/package/agent-browser)

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

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

### [`browser-use`](https://pypi.org/project/browser-use/)

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

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

### [`browse`](https://www.npmjs.com/package/browse)（コマンド: `browse`）

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

```bash
npm install -g browse
browse skills install
```

## 関連項目

- [BrowserViewer ガイド](https://mastra.zisheng.pro/ja/docs/browser/browser-viewer): セットアップと使用方法のチュートリアル
- [MastraBrowser](https://mastra.zisheng.pro/ja/reference/browser/mastra-browser): 基底クラスの API リファレンス
- [Workspace の概要](https://mastra.zisheng.pro/ja/docs/workspace/overview): Workspace の設定