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

# AgentBrowser

`@mastra/agent-browser` パッケージは、アクセシビリティを優先した要素指定を使用する Playwright ベースのブラウザ自動化を提供します。ページのアクセシビリティツリーから取得した ref で要素を識別するため、ページレイアウトが変わっても安定して操作できます。

## AgentBrowser を使用する場面

次のような場合に AgentBrowser を使用します。

- アクセシビリティ ref を利用して要素を確実に指定したい
- ブラウザ操作を細かく制御したい
- Playwright の信頼性の高い自動化機能を利用したい
- キーボードショートカットや複雑な操作をサポートしたい

## クイックスタート

パッケージをインストールします。

**npm**:

```bash
npm install @mastra/agent-browser
```

**pnpm**:

```bash
pnpm add @mastra/agent-browser
```

**Yarn**:

```bash
yarn add @mastra/agent-browser
```

**Bun**:

```bash
bun add @mastra/agent-browser
```

ブラウザインスタンスを作成し、Agent に割り当てます。

```typescript
import { Agent } from '@mastra/core/agent'
import { AgentBrowser } from '@mastra/agent-browser'

const browser = new AgentBrowser({
  headless: false,
})

export const browserAgent = new Agent({
  id: 'browser-agent',
  name: 'Browser Agent',
  model: 'openai/gpt-5.6-sol',
  browser,
  instructions: `You are a web automation assistant.

When interacting with pages:
1. Use browser_snapshot to get the current page state and element refs
2. Use the refs (like @e1, @e2) to target elements for clicks and typing
3. After actions, take another snapshot to verify the result`,
})
```

> **注記:** ローカル起動（デフォルト）の場合、AgentBrowser には Playwright でインストールした Chromium バイナリが必要です。通常は `@mastra/agent-browser` のインストール時に自動でダウンロードされます。ブラウザの起動時に `"browser executable is missing"` というエラーが発生した場合は、`npx playwright install chromium` を実行してください。[`cdpUrl`](https://mastra.zisheng.pro/ja/reference/browser/agent-browser) オプションでリモートブラウザに接続する場合、Chromium はリモートブラウザ側から提供されます。

## スクリーンショット

Agent が `browser_screenshot` Tool を使用すると、現在のページを PNG 画像としてキャプチャし、Vision 対応モデルが直接解釈できる画像コンテンツとして返します。

画像、レイアウト、色など、ページを視覚的に確認する必要がある場合はスクリーンショットを使用します。テキストや構造化データには、代わりに `browser_snapshot` を使用してください。

Vision をサポートしないモデルでスクリーンショット Tool を無効にするには、`excludeTools` を使用します。

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

## 要素の ref

AgentBrowser は、アクセシビリティツリーの ref を使用して要素を識別します。Agent が `browser_snapshot` を呼び出すと、`@e1`、`@e2` などの ref を含むページのテキスト表現を受け取ります。Agent はこれらの ref をほかの Tool で使用して要素を操作します。

## 録画

AgentBrowser では、アルファ版のブラウザ録画 Tool をオプトインで有効にできます。

```typescript
const browser = new AgentBrowser({
  headless: false,
  recording: {
    outputDir: './browser-recordings',
  },
})
```

これにより、Agent の Tool セットに `browser_record` と `browser_record_caption` が追加されます。詳細は[ブラウザ録画（アルファ版）](https://mastra.zisheng.pro/ja/docs/browser/recording)を参照してください。すべての設定オプションと Tool の詳細については、[AgentBrowser リファレンス](https://mastra.zisheng.pro/ja/reference/browser/agent-browser)を参照してください。

## 関連情報

- [Browser の概要](https://mastra.zisheng.pro/ja/docs/browser/overview)
- [Stagehand](https://mastra.zisheng.pro/ja/docs/browser/stagehand)
- [Firecrawl](https://mastra.zisheng.pro/ja/docs/browser/firecrawl)
- [ブラウザ録画（アルファ版）](https://mastra.zisheng.pro/ja/docs/browser/recording)
- [AgentBrowser リファレンス](https://mastra.zisheng.pro/ja/reference/browser/agent-browser)