跳至主要內容

AgentBrowser

@mastra/agent-browser 依賴套件使用 Playwright 提供瀏覽器自動化功能，並以無障礙優先的方式定位元素。元素透過頁面無障礙樹中的 refs 識別，令互動在不同頁面佈局下仍然可靠。

何時使用 AgentBrowser
何時使用 AgentBrowser 的直接連結

當你需要以下功能時，請使用 AgentBrowser：

  • 透過無障礙 refs 可靠地定位元素
  • 精細控制瀏覽器操作
  • 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。

如要為不支援視覺功能的模型停用螢幕截圖 Tool，請使用 excludeTools：

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

元素 refs
元素 refs 的直接連結

AgentBrowser 使用無障礙樹 refs 識別元素。當 Agent 呼叫 browser_snapshot 時，它會收到頁面的文字表示，其中包含 @e1、@e2 等 refs。然後，Agent 會配合其他 Tool 使用這些 refs 與元素互動。

錄製
錄製 的直接連結

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