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

# MastraBrowser クラス

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

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

- [`AgentBrowser`](https://mastra.zisheng.pro/ja/reference/browser/agent-browser): refs を使用した決定論的なブラウザ自動化
- [`StagehandBrowser`](https://mastra.zisheng.pro/ja/reference/browser/stagehand-browser): 自然言語を使用した AI 駆動のブラウザ自動化
- [`BrowserViewer`](https://mastra.zisheng.pro/ja/reference/browser/browser-viewer): CDP URL インジェクションを使用した CLI ベースのブラウザ自動化

## 使用例

```typescript
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`): ヘッドレスモード（表示 UI なし）でブラウザを実行するかどうか。 (Default: `true`)

**viewport** (`{ width: number; height: number } | 'window'`): ブラウザのビューポート寸法。ブラウザウィンドウのサイズを制御します。固定サイズではなく実際のブラウザウィンドウに合わせるには 'window' を設定します。これは agent-browser Provider、および CDP 経由で接続する場合の Stagehand でサポートされています。 (Default: `{ width: 1280, height: 720 }`)

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

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

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

**onLaunch** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): ブラウザが 'ready' ステータスに達した後に呼び出されるコールバック。

**onClose** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): ブラウザが閉じられる前に呼び出されるコールバック。

**screencast** (`ScreencastOptions`): ブラウザフレームをストリーミングするための設定。

**screencast.format** (`'jpeg' | 'png'`): スクリーンキャストフレームの画像形式。

**screencast.quality** (`number`): 画像品質（1～100）。JPEG 形式にのみ適用されます。

**screencast.maxWidth** (`number`): スクリーンキャストフレームの最大幅。

**screencast.maxHeight** (`number`): スクリーンキャストフレームの最大高さ。

**screencast.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 の実行前に自動的に呼び出されます。基底クラスに実装されています。

```typescript
await browser.ensureReady()
```

#### `close()`

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

```typescript
await browser.close()
```

#### `isBrowserRunning()`

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

```typescript
const isRunning = browser.isBrowserRunning()
```

**戻り値:** `boolean`

### スレッド管理

#### `setCurrentThread(threadId)`

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

```typescript
browser.setCurrentThread('thread-123')
```

#### `getCurrentThread()`

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

```typescript
const threadId = browser.getCurrentThread()
```

**戻り値:** `string`

#### `hasThreadSession(threadId)`

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

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

**戻り値:** `boolean`

#### `closeThreadSession(threadId)`

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

```typescript
await browser.closeThreadSession('thread-123')
```

### Tool

#### `getTools()`

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

```typescript
const tools = browser.getTools()
```

**戻り値:** `Record<string, Tool>`

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

#### `startScreencast(options?, threadId?)`

ブラウザフレームのストリーミングを開始します。フレームイベントを発行する `ScreencastStream` を返します。

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

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

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

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

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

### 状態

#### `getState(threadId?)`

URL とタブを含む現在のブラウザ状態を取得します。

```typescript
const state = await browser.getState('thread-123')
console.log('Current URL:', state.currentUrl)
console.log('Tabs:', state.tabs)
```

**戻り値:** `Promise<BrowserState>`

```typescript
interface BrowserState {
  currentUrl: string | null
  tabs: BrowserTabState[]
  activeTabIndex: number
}

interface BrowserTabState {
  id: string
  url: string
  title: string
}
```

#### `getCurrentUrl(threadId?)`

現在のページ URL を取得します。

```typescript
const url = await browser.getCurrentUrl()
```

**戻り値:** `Promise<string | null>`

## ブラウザの scope

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

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

```typescript
// 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` オプションを使用してクラウドブラウザサービスへ接続します。

```typescript
// 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](https://mastra.zisheng.pro/ja/reference/browser/agent-browser): 決定論的なブラウザ自動化
- [StagehandBrowser](https://mastra.zisheng.pro/ja/reference/browser/stagehand-browser): AI 駆動のブラウザ自動化
- [Browser の概要](https://mastra.zisheng.pro/ja/docs/browser/overview): ブラウザ自動化の概念ガイド