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

# AgentBrowser クラス

`AgentBrowser` クラスは、[agent-browser](https://github.com/vercel-labs/agent-browser) ライブラリを使用した決定論的なブラウザー自動化を提供します。アクセシビリティツリーのスナップショットと要素 ref（`@e5` など）を使用することで、正確で再現可能な操作を実現します。

信頼性と決定性のあるブラウザー自動化が必要な場合は、`AgentBrowser` を使用します。自然言語を使用した AI による操作については、[`StagehandBrowser`](https://mastra.zisheng.pro/ja/reference/browser/stagehand-browser) を参照してください。

## 使用例

```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. Use browser_snapshot to see the page structure,
then interact with elements using their refs (e.g., @e5).`,
  model: 'openai/gpt-5.6-sol',
  browser,
})
```

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

**headless** (`boolean`): ブラウザーをヘッドレスモード（UI を表示しない状態）で実行するかどうか。 (Default: `true`)

**viewport** (`{ width: number; height: number } | 'window'`): ブラウザーのビューポートサイズ。固定サイズではなく実際のブラウザーウィンドウに合わせるには 'window' を指定します。 (Default: `{ width: 1280, height: 720 }`)

**timeout** (`number`): ブラウザー操作のデフォルトタイムアウト（ミリ秒）。 (Default: `30000`)

**cdpUrl** (`string | (() => string | Promise<string>)`): 既存のブラウザーに接続するための CDP WebSocket URL。クラウドブラウザー Provider に便利です。

**scope** (`'shared' | 'thread'`): ブラウザーインスタンスの scope。'shared' では1つのブラウザーをすべてのスレッドで共有します。'thread' では各スレッドに専用のブラウザーを割り当てます。 (Default: `'thread' (or 'shared' when cdpUrl is provided)`)

**onLaunch** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): ブラウザーの準備が完了した後に呼び出されるコールバック。

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

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

**recording** (`BrowserRecordingOptions`): ブラウザー録画 Tool を追加するためのアルファ版オプション。outputDir を指定すると、Tool セットに browser\_record と browser\_record\_caption が追加されます。すべての録画のデフォルト値として maxDurationMs、maxWidth、maxHeight も設定できます。

**excludeTools** (`BrowserToolName[]`): ブラウザーの Tool セットから除外する Tool 名。Vision などの特定の機能に対応していないモデル向けに、特定の Tool を無効化する場合に使用します。

## Tool

`AgentBrowser` は、ブラウザー自動化用の16個の決定論的な Tool を提供します。要素を操作するすべての Tool は、アクセシビリティツリーのスナップショットから取得した ref を使用します。

`recording` を設定すると、`AgentBrowser` はアルファ版の `browser_record` Tool と `browser_record_caption` Tool も追加します。[ブラウザー録画（アルファ版）](https://mastra.zisheng.pro/ja/docs/browser/recording)を参照してください。

### コア Tool

| Tool                 | 説明                                                                       |
| -------------------- | ------------------------------------------------------------------------ |
| `browser_goto`       | URL に移動します                                                               |
| `browser_snapshot`   | 要素 ref を含むアクセシビリティツリーのスナップショットを取得します                                     |
| `browser_click`      | ref を指定して要素をクリックします                                                      |
| `browser_type`       | 要素にテキストを入力します                                                            |
| `browser_press`      | キーボードのキーを押します                                                            |
| `browser_select`     | ドロップダウンからオプションを選択します                                                     |
| `browser_scroll`     | ページまたは要素をスクロールします                                                        |
| `browser_screenshot` | PNG 形式でスクリーンショットを撮影します（デフォルトはビューポートのみ。ページ全体を撮影するには `fullPage: true` を設定） |
| `browser_close`      | ブラウザーを閉じます                                                               |

### 拡張 Tool

| Tool               | 説明                                     |
| ------------------ | -------------------------------------- |
| `browser_hover`    | 要素にカーソルを合わせます                          |
| `browser_back`     | ブラウザーの履歴を戻ります                          |
| `browser_dialog`   | ブラウザーダイアログ（alert、confirm、prompt）を処理します |
| `browser_wait`     | 要素の状態が変化するまで待機します                      |
| `browser_tabs`     | ブラウザーのタブを管理します（一覧表示、新規作成、切り替え、閉じる）     |
| `browser_drag`     | 要素をドラッグ＆ドロップします                        |
| `browser_evaluate` | ページ内で JavaScript を実行します（エスケープハッチ）      |

特定の Tool を除外するには、コンストラクターに `excludeTools` を渡します。

```typescript
const browser = new AgentBrowser({
  excludeTools: ['browser_screenshot'],
})
```

## Tool リファレンス

### `browser_goto`

URL に移動します。

```text
// Tool input
{
  "url": "https://example.com",
  "waitUntil": "domcontentloaded",
  "timeout": 30000
}
```

| パラメーター      | 型                                               | 説明                        |
| ----------- | ----------------------------------------------- | ------------------------- |
| `url`       | `string`                                        | 開く URL                    |
| `waitUntil` | `"load" \| "domcontentloaded" \| "networkidle"` | ナビゲーションが完了したとみなすタイミング（任意） |
| `timeout`   | `number`                                        | ナビゲーションのタイムアウト（ミリ秒、任意）    |

### `browser_snapshot`

ページのアクセシビリティツリーのスナップショットを取得します。ほかの Tool で使用する `@e5` などの要素 ref を返します。

```text
// Tool input
{
  "interactiveOnly": true,
  "maxDepth": 10
}
```

| パラメーター            | 型         | 説明                    |
| ----------------- | --------- | --------------------- |
| `interactiveOnly` | `boolean` | 操作可能な要素のみを含めるかどうか（任意） |
| `maxDepth`        | `number`  | ツリーの最大深度（任意）          |

**出力例:**

```text
[document] Example Page
  [banner]
    [link @e1] Home
    [link @e2] About
  [main]
    [heading @e3] Welcome
    [textbox @e4] Search...
    [button @e5] Submit
```

### `browser_click`

スナップショットの ref を使用して要素をクリックします。

```text
{
  "ref": "@e5",
  "button": "left",
  "clickCount": 1,
  "modifiers": ["Control", "Shift"]
}
```

| パラメーター       | 型                               | 説明                     |
| ------------ | ------------------------------- | ---------------------- |
| `ref`        | `string`                        | スナップショット内の要素 ref（必須）   |
| `button`     | `"left" \| "right" \| "middle"` | マウスボタン（任意）             |
| `clickCount` | `number`                        | 実行回数。ダブルクリックの場合は 2（任意） |
| `modifiers`  | `string[]`                      | 修飾キー（任意）               |

### `browser_type`

入力要素にテキストを入力します。

```text
// Tool input
{
  "ref": "@e4",
  "text": "search query",
  "clear": true,
  "delay": 50
}
```

| パラメーター  | 型         | 説明                   |
| ------- | --------- | -------------------- |
| `ref`   | `string`  | スナップショット内の要素 ref（必須） |
| `text`  | `string`  | 入力するテキスト（必須）         |
| `clear` | `boolean` | 既存の内容を先に消去するかどうか（任意） |
| `delay` | `number`  | キー入力間の遅延（ミリ秒、任意）     |

### `browser_press`

キーボードのキーを押します。

```text
// Tool input
{
  "key": "Enter",
  "modifiers": ["Control"]
}

// Key combinations
{ "key": "Control+a" }
{ "key": "Control+c" }
```

| パラメーター      | 型          | 説明                                             |
| ----------- | ---------- | ---------------------------------------------- |
| `key`       | `string`   | キー名（例: "Enter"、"Tab"、"Escape"、"Control+a"）（必須） |
| `modifiers` | `string[]` | 修飾キー（任意）                                       |

### `browser_select`

ドロップダウンからオプションを選択します。`value`、`label`、`index` のいずれかを指定します。

```text
// Tool input - by value
{
  "ref": "@e10",
  "value": "option-value"
}

// Tool input - by label
{
  "ref": "@e10",
  "label": "Option Text"
}

// Tool input - by index
{
  "ref": "@e10",
  "index": 0
}
```

### `browser_scroll`

ページまたは特定の要素をスクロールします。

```text
// Tool input
{
  "direction": "down",
  "amount": 300,
  "ref": "@e15"
}
```

| パラメーター      | 型                                     | 説明                           |
| ----------- | ------------------------------------- | ---------------------------- |
| `direction` | `"up" \| "down" \| "left" \| "right"` | スクロール方向（必須）                  |
| `amount`    | `number`                              | スクロールするピクセル数。デフォルトは 300（任意）  |
| `ref`       | `string`                              | スクロールする要素。省略するとページをスクロール（任意） |

### `browser_hover`

要素にカーソルを合わせ、ホバー効果を発生させます。

```text
// Tool input
{
  "ref": "@e7"
}
```

### `browser_back`

ブラウザーの履歴を戻ります。

```text
// Tool input (no parameters required)

```

### `browser_dialog`

ブラウザーダイアログ（alert、confirm、prompt）を処理します。ダイアログを発生させる要素をクリックし、そのダイアログを処理します。

```text
// Tool input
{
  "triggerRef": "@e5",
  "action": "accept",
  "text": "response"
}
```

| パラメーター       | 型                       | 説明                        |
| ------------ | ----------------------- | ------------------------- |
| `triggerRef` | `string`                | ダイアログを発生させる要素（必須）         |
| `action`     | `"accept" \| "dismiss"` | ダイアログの処理方法（必須）            |
| `text`       | `string`                | prompt ダイアログに入力するテキスト（任意） |

### `browser_wait`

要素が指定した状態になるまで待機します。

```text
// Tool input
{
  "ref": "@e20",
  "state": "visible",
  "timeout": 30000
}
```

| パラメーター    | 型                                                   | 説明              |
| --------- | --------------------------------------------------- | --------------- |
| `ref`     | `string`                                            | 待機対象の要素 ref（任意） |
| `state`   | `"visible" \| "hidden" \| "attached" \| "detached"` | 待機する状態（任意）      |
| `timeout` | `number`                                            | 最大待機時間（ミリ秒、任意）  |

### `browser_tabs`

ブラウザーのタブを管理します。

```text
// List all tabs
{ "action": "list" }

// Open new tab
{ "action": "new", "url": "https://example.com" }

// Switch to tab by index
{ "action": "switch", "index": 0 }

// Close tab by index
{ "action": "close", "index": 1 }
```

### `browser_drag`

要素を対象の位置までドラッグします。

```text
// Tool input
{
  "sourceRef": "@e10",
  "targetRef": "@e20"
}
```

| パラメーター      | 型        | 説明           |
| ----------- | -------- | ------------ |
| `sourceRef` | `string` | ドラッグする要素（必須） |
| `targetRef` | `string` | ドロップ先の要素（必須） |

### `browser_evaluate`

ページのコンテキスト内で JavaScript を実行します。ほかの Tool ではユースケースに対応できない場合のエスケープハッチとして使用します。

```text
// Tool input
{
  "script": "document.title",
  "returnValue": true
}
```

| パラメーター        | 型         | 説明                  |
| ------------- | --------- | ------------------- |
| `script`      | `string`  | 実行する JavaScript（必須） |
| `returnValue` | `boolean` | 結果を返すかどうか（任意）       |

### `browser_screenshot`

現在のページを PNG 形式で撮影します（デフォルトはビューポートのみ。ページ全体を撮影するには `fullPage: true` を設定します）。Vision 対応モデルが直接解釈できる画像コンテンツを返します。テキストまたは構造化データのみが必要な場合は、`browser_snapshot` を使用してください。

```text
// Viewport only (default)

// Full scrollable page
{ "fullPage": true }
```

| パラメーター     | 型         | 説明                                                  |
| ---------- | --------- | --------------------------------------------------- |
| `fullPage` | `boolean` | ビューポートだけでなく、スクロール可能なページ全体を撮影するかどうか（任意、デフォルト: false） |

### `browser_close`

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

```text
// Tool input (no parameters required)

```

## ref の仕組み

`browser_snapshot` Tool は、`@e1`、`@e2` などの要素 ref を含むアクセシビリティツリーを返します。これらの ref は、ほかの Tool で使用する安定した識別子です。

1. `browser_snapshot` を呼び出してページ構造を確認します
2. 操作する要素を見つけます
3. `browser_type` や `browser_scroll` などの操作 Tool に、その要素の ref を指定します。

```text
// 1. Get snapshot
// Returns: [textbox @e4] Search... [link @e5] Home

// 2. Type in the search box
{ "tool": "browser_type", "input": { "ref": "@e4", "text": "mastra" } }

// 3. Navigate to home
{ "tool": "browser_goto", "input": { "url": "https://example.com" } }
```

## 関連項目

- [MastraBrowser](https://mastra.zisheng.pro/ja/reference/browser/mastra-browser): 基底クラスのリファレンス
- [StagehandBrowser](https://mastra.zisheng.pro/ja/reference/browser/stagehand-browser): AI を利用した代替手段
- [Browser の概要](https://mastra.zisheng.pro/ja/docs/browser/overview): コンセプトガイド
- [agent-browser ガイド](https://mastra.zisheng.pro/ja/docs/browser/agent-browser): 使用ガイド