AgentBrowser クラス

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

信頼性と決定性のあるブラウザー自動化が必要な場合は、AgentBrowser を使用します。自然言語を使用した AI による操作については、StagehandBrowser を参照してください。

使用例

src/mastra/agents/index.ts

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

= true

ブラウザーをヘッドレスモード（UI を表示しない状態）で実行するかどうか。

viewport?:

{ width: number; height: number } | 'window'

= { width: 1280, height: 720 }

ブラウザーのビューポートサイズ。固定サイズではなく実際のブラウザーウィンドウに合わせるには 'window' を指定します。

timeout?:

number

= 30000

ブラウザー操作のデフォルトタイムアウト（ミリ秒）。

cdpUrl?:

string | (() => string | Promise<string>)

既存のブラウザーに接続するための CDP WebSocket URL。クラウドブラウザー Provider に便利です。

scope?:

'shared' | 'thread'

= 'thread' (or 'shared' when cdpUrl is provided)

ブラウザーインスタンスの scope。'shared' では1つのブラウザーをすべてのスレッドで共有します。'thread' では各スレッドに専用のブラウザーを割り当てます。

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 も追加します。ブラウザー録画（アルファ版）を参照してください。

コア 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 を渡します。

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

Tool リファレンス

browser_goto

URL に移動します。

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

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

browser_snapshot

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

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

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

出力例:

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

browser_click

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

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

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

browser_type

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

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

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

browser_press

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

// 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 のいずれかを指定します。

// 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

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

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

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

browser_hover

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

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

browser_back

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

// Tool input (no parameters required)
{}

browser_dialog

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

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

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

browser_wait

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

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

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

browser_tabs

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

// 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

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

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

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

browser_evaluate

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

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

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

browser_screenshot

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

// Viewport only (default)
{}

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

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

browser_close

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

// 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 を指定します。

// 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: 基底クラスのリファレンス
• StagehandBrowser: AI を利用した代替手段
• Browser の概要: コンセプトガイド
• agent-browser ガイド: 使用ガイド