AgentBrowser 類別

AgentBrowser 類別使用 agent-browser library 提供確定性瀏覽器自動化。它使用 accessibility tree snapshot 與 element 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 集合。也可設定 maxDurationMs、maxWidth 與 maxHeight，作為每次錄製的預設值。

excludeTools?:

BrowserToolName[]

要從瀏覽器 Tool 集合排除的 Tool 名稱。可用於停用模型不支援的特定能力，例如 vision。

Tool

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

設定 recording 後，AgentBrowser 也會加入 Alpha 版的 browser_record 與 browser_record_caption Tool。請參閱瀏覽器錄製（Alpha）。

核心 Tool

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

擴充 Tool

Tool	說明
browser_hover	將游標移至 element 上方
browser_back	回到瀏覽器上一頁
browser_dialog	處理瀏覽器 dialog（alert、confirm、prompt）
browser_wait	等待 element state 改變
browser_tabs	管理瀏覽器分頁（列出、新增、切換、關閉）
browser_drag	拖放 element
browser_evaluate	在頁面中執行 JavaScript（例外處理機制）

若要排除特定 Tool，請將 excludeTools 傳給 constructor：

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 等 element ref，供其他 Tool 使用。

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

參數	型別	說明
interactiveOnly	boolean	只包含互動式 element（選填）
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 點擊 element。

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

參數	型別	說明
ref	string	snapshot 中的 element ref（必填）
button	"left" | "right" | "middle"	滑鼠按鈕（選填）
clickCount	number	啟用次數；2 表示按兩下（選填）
modifiers	string[]	modifier key（選填）

browser_type

在輸入 element 中輸入文字。

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

參數	型別	說明
ref	string	snapshot 中的 element 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

捲動頁面或特定 element。

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

參數	型別	說明
direction	"up" | "down" | "left" | "right"	捲動方向（必填）
amount	number	捲動的像素數，預設 300（選填）
ref	string	要捲動的 element；省略時捲動頁面（選填）

browser_hover

將游標移至 element 上方，以觸發 hover 效果。

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

browser_back

回到瀏覽器上一頁。

// Tool input (no parameters required)
{}

browser_dialog

處理瀏覽器 dialog（alert、confirm、prompt）。點擊會觸發 dialog 的 element，並加以處理。

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

參數	型別	說明
triggerRef	string	觸發 dialog 的 element（必填）
action	"accept" | "dismiss"	dialog 的處理方式（必填）
text	string	prompt dialog 的文字（選填）

browser_wait

等待 element 進入特定 state。

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

參數	型別	說明
ref	string	要等待的 element ref（選填）
state	"visible" | "hidden" | "attached" | "detached"	要等待的 state（選填）
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

將 element 拖曳至目標位置。

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

參數	型別	說明
sourceRef	string	要拖曳的 element（必填）
targetRef	string	放置目標 element（必填）

browser_evaluate

在頁面 context 中執行 JavaScript。其他 Tool 無法涵蓋使用情境時，可作為例外處理機制。

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

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

browser_screenshot

將目前頁面擷取為 PNG 螢幕截圖（預設為 viewport；設定 fullPage: true 可擷取完整頁面）。傳回的圖片內容可由具備 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 會傳回含有 @e1、@e2 等 element ref 的 accessibility tree。這些 ref 是供其他 Tool 使用的穩定識別碼：

1. 呼叫 browser_snapshot 查看頁面結構
2. 找出要互動的 element
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：基底類別參考文件
• StagehandBrowser：AI 驅動的替代方案
• Browser 概觀：概念指南
• agent-browser 指南：使用指南