跳至主要內容

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 圖片，並以支援視覺功能的模型可直接解讀的圖片內容回傳。

需要以視覺方式檢查頁面時（例如評估圖片、版面或色彩），請使用螢幕截圖。若要取得文字或結構化資料，請改用 browser_snapshot。

若模型不支援視覺功能，可使用 excludeTools 停用螢幕截圖 Tool：

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

元素 ref
「元素 ref」的直接連結

AgentBrowser 使用無障礙樹 ref 識別元素。當 Agent 呼叫 browser_snapshot 時，會收到頁面的文字表示，其中包含 @e1、@e2 等 ref。接著，Agent 會將這些 ref 搭配其他 Tool 使用，以便與元素互動。

錄製
「錄製」的直接連結

AgentBrowser 可選擇啟用 alpha 階段的瀏覽器錄製 Tool：

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

這會將 browser_record 和 browser_record_caption 加入 Agent 的 Tool 集合。詳情請參閱瀏覽器錄製（alpha）。所有設定選項和 Tool 詳情請參閱 AgentBrowser 參考文件。

On this page