メインコンテンツへ移動

AgentBrowser

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

AgentBrowser を使用する場面
AgentBrowser を使用する場面への直接リンク

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

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

クイックスタート
クイックスタートへの直接リンク

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

npm install @mastra/agent-browser

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

src/mastra/agents/browser-agent.ts
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 オプションでリモートブラウザに接続する場合、Chromium はリモートブラウザ側から提供されます。

スクリーンショット
スクリーンショットへの直接リンク

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

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

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

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

要素の ref
要素の refへの直接リンク

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

録画
録画への直接リンク

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

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

これにより、Agent の Tool セットに browser_record と browser_record_caption が追加されます。詳細はブラウザ録画（アルファ版）を参照してください。すべての設定オプションと Tool の詳細については、AgentBrowser リファレンスを参照してください。

On this page