AgentBrowser class

AgentBrowser class 使用 agent-browser library 提供確定性瀏覽器自動化。它運用 accessibility tree snapshot 及元素 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,
})

Constructor 參數

headless?:

boolean

= true

是否以 headless 模式執行瀏覽器（不顯示 UI）。

viewport?:

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

= { width: 1280, height: 720 }

瀏覽器 viewport 尺寸；亦可設為 'window'，以配合實際瀏覽器視窗，而非使用固定尺寸。

timeout?:

number

= 30000

瀏覽器操作的預設逾時時間（毫秒）。

cdpUrl?:

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

用於連線至現有瀏覽器的 CDP WebSocket URL，適合配合雲端瀏覽器 Provider 使用。

scope?:

'shared' | 'thread'

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

瀏覽器 instance scope。'shared' 讓所有 thread 共用一個瀏覽器；'thread' 則讓每個 thread 都有自己的瀏覽器。

onLaunch?:

(args: { browser: MastraBrowser }) => void | Promise<void>

瀏覽器準備就緒後呼叫的 callback。

onClose?:

(args: { browser: MastraBrowser }) => void | Promise<void>

關閉瀏覽器前呼叫的 callback。

screencast?:

ScreencastOptions

將瀏覽器 frame 串流至 Studio 的設定。

recording?:

BrowserRecordingOptions

用於加入瀏覽器錄影 Tool 的 Alpha 選項。提供 outputDir，即可將 browser_record 及 browser_record_caption 加入 Tool set。你亦可設定 maxDurationMs、maxWidth 及 maxHeight，作為每次錄影的預設值。

excludeTools?:

BrowserToolName[]

要從瀏覽器 Tool set 排除的 Tool 名稱。如模型不支援 vision 等特定功能，可使用此選項停用相應 Tool。

Tools

AgentBrowser 提供 16 個用於瀏覽器自動化的確定性 Tool。所有與元素互動的 Tool，都會使用 accessibility tree snapshot 中的 ref。

設定 recording 後，AgentBrowser 亦會加入 Alpha 版 browser_record 及 browser_record_caption Tool。請參閱瀏覽器錄影（Alpha）。

核心 Tool

Tool	說明
browser_goto	前往 URL
browser_snapshot	取得包含元素 ref 的 accessibility tree snapshot
browser_click	按 ref 點擊元素
browser_type	在元素中輸入文字
browser_press	按下鍵盤按鍵
browser_select	從下拉式選單選取選項
browser_scroll	捲動頁面或元素
browser_screenshot	擷取 PNG 螢幕截圖（預設只擷取 viewport；如要擷取完整頁面，請設為 fullPage: true）
browser_close	關閉瀏覽器

擴充 Tool

Tool	說明
browser_hover	將游標停留在元素上
browser_back	返回瀏覽器上一頁
browser_dialog	處理瀏覽器 dialog（alert、confirm、prompt）
browser_wait	等待元素狀態變更
browser_tabs	管理瀏覽器分頁（列出、建立、切換、關閉）
browser_drag	拖放元素
browser_evaluate	在頁面中執行 JavaScript（應急方法）

如要排除特定 Tool，請在 constructor 傳入 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

取得頁面的 accessibility tree snapshot。傳回 @e5 等元素 ref，供其他 Tool 使用。

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

參數	類型	說明
interactiveOnly	boolean	只包括可互動元素（可選）
maxDepth	number	Tree 的最大深度（可選）

輸出範例：

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

browser_click

使用 snapshot 中的 ref 點擊元素。

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

參數	類型	說明
ref	string	Snapshot 中的元素 ref（必填）
button	"left" | "right" | "middle"	滑鼠按鈕（可選）
clickCount	number	啟動次數；設為 2 即代表連按兩下（可選）
modifiers	string[]	Modifier key（可選）

browser_type

在 input 元素中輸入文字。

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

參數	類型	說明
ref	string	Snapshot 中的元素 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[]	Modifier key（可選）

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

將游標停留在元素上，以觸發 hover 效果。

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

browser_back

在瀏覽器歷史記錄中返回上一頁。

// Tool input (no parameters required)
{}

browser_dialog

處理瀏覽器 dialog（alert、confirm、prompt）。點擊會觸發 dialog 的元素，然後處理該 dialog。

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

參數	類型	說明
triggerRef	string	會觸發 dialog 的元素（必填）
action	"accept" | "dismiss"	處理 dialog 的方式（必填）
text	string	用於 prompt dialog 的文字（可選）

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

在頁面 context 中執行 JavaScript。當其他 Tool 未能涵蓋你的使用情境時，可將此方法作為應急方案。

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

參數	類型	說明
script	string	要執行的 JavaScript（必填）
returnValue	boolean	是否傳回結果（可選）

browser_screenshot

將目前頁面擷取成 PNG 螢幕截圖（預設只擷取 viewport；設定 fullPage: true 可擷取完整頁面）。此 Tool 會傳回具 vision 功能的模型可直接理解的影像內容。如果只需要文字或結構化資料，請使用 browser_snapshot。

// Viewport only (default)
{}

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

參數	類型	說明
fullPage	boolean	擷取整個可捲動頁面，而非只擷取 viewport（可選，預設：false）

browser_close

關閉瀏覽器並清理資源。

// Tool input (no parameters required)
{}

Ref 的運作方式

browser_snapshot Tool 會傳回 accessibility tree，其中包含 @e1、@e2 等元素 ref。這些 ref 是可配合其他 Tool 使用的穩定識別碼：

1. 呼叫 browser_snapshot 查看頁面結構
2. 找出你想互動的元素
3. 將其 ref 配合 browser_type 或 browser_scroll 等互動 Tool 使用。

// 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：基底 class 參考
• StagehandBrowser：AI 替代方案
• 瀏覽器概覽：概念指南
• agent-browser 指南：使用指南