瀏覽器概覽

瀏覽器支援讓 Agent 能夠瀏覽網站、與頁面元素互動、填寫表格及擷取數據。Mastra 透過封裝瀏覽器自動化程式庫的 SDK Provider，以及供 Agent 使用命令列 Tool 操控瀏覽器的 CLI Provider，提供瀏覽器功能。

Mastra 支援三個 SDK Provider 和一個 CLI Provider：

• AgentBrowser：以 Playwright 為基礎的 Provider，優先使用無障礙功能定位元素。最適合一般網絡自動化及資料抓取。
• Stagehand：具備 AI 元素偵測功能的 Browserbase Provider。最適合能受惠於自然語言選擇器的複雜互動。
• FirecrawlBrowser：在託管瀏覽器工作階段中執行 AgentBrowser Tool 的 Firecrawl Browser Sandbox Provider。最適合在無需管理本機瀏覽器基礎設施的情況下，於託管瀏覽器工作階段中執行自動化操作。
• BrowserViewer：啟動 Chrome，並將 CDP URL 注入 agent-browser、browser-use 和 browse 等 CLI Tool 的 CLI Provider。最適合透過 shell 命令操控瀏覽器的 Workspace Agent。
• 瀏覽器錄影（alpha）：可選用的 Tool 層，將瀏覽器工作階段儲存為 Motion-JPEG AVI 影片，並可選擇加入字幕。

何時使用瀏覽器

當你的 Agent 需要執行以下操作時，便應使用瀏覽器：

• 瀏覽網站並與頁面元素互動
• 填寫表格及提交數據
• 從網頁擷取結構化數據
• 自動執行多步驟網絡 Workflow
• 執行需要真實瀏覽器的操作（JavaScript 渲染、驗證流程）

運作方式

當你為 Agent 指派瀏覽器時，Mastra 會將該 Provider 的 Tool 加入 Agent 的 Tool 集合。Agent 使用這些 Tool 控制瀏覽器，包括前往 URL、選取元素、輸入文字及讀取頁面內容。

每個 Provider 都會因應其運作方式，提供一套經過最佳化的不同 Tool。

快速開始

安裝你選擇的 Provider；在此範例中，你會使用 AgentBrowser Provider。

npm

npm install @mastra/agent-browser

pnpm

pnpm add @mastra/agent-browser

Yarn

yarn add @mastra/agent-browser

Bun

bun add @mastra/agent-browser

建立新的瀏覽器實例：

src/mastra/browsers.ts

import { AgentBrowser } from '@mastra/agent-browser'

export const browser = new AgentBrowser({
  headless: false,
})

將瀏覽器指派給 Agent：

src/mastra/agents/web-agent.ts

import { Agent } from '@mastra/core/agent'
import { browser } from '../browsers'

export const webAgent = new Agent({
  id: 'web-agent',
  name: 'Web Agent',
  description: 'A web automation assistant that can navigate websites and complete tasks.',
  model: 'openai/gpt-5.6-sol',
  browser,
  instructions:
    'You are a web automation assistant. Use browser tools to navigate websites and complete tasks.',
})

Agent 會自動取得該 Provider 的所有瀏覽器 Tool。

雲端 Provider

所有 SDK Provider 都支援連接雲端瀏覽器服務，無需啟動本機瀏覽器。

Firecrawl Browser Sandbox（FirecrawlBrowser 原生支援）

FirecrawlBrowser 透過 Firecrawl API 建立託管工作階段：

import { FirecrawlBrowser } from '@mastra/browser-firecrawl'

const browser = new FirecrawlBrowser({
  apiKey: process.env.FIRECRAWL_API_KEY,
})

Browserbase（Stagehand 原生支援）

Stagehand 原生整合 Browserbase：

import { StagehandBrowser } from '@mastra/stagehand'

const browser = new StagehandBrowser({
  env: 'BROWSERBASE',
  apiKey: process.env.BROWSERBASE_API_KEY,
  projectId: process.env.BROWSERBASE_PROJECT_ID,
})

CDP URL（任何 Provider）

連接至任何提供 Chrome DevTools Protocol（CDP）端點的瀏覽器：

import { AgentBrowser } from '@mastra/agent-browser'

const browser = new AgentBrowser({
  cdpUrl: process.env.BROWSER_CDP_URL,
  headless: true,
})

此方式適用於任何兼容 CDP 的瀏覽器服務。

畫面串流

瀏覽器 Provider 會將瀏覽器的即時影片串流至 Mastra Studio UI，讓你可以即時觀看 Agent 與頁面互動。

畫面串流需要 WebSocket 支援。請在你的項目中安裝以下依賴套件：

npm

npm install ws @hono/node-ws

pnpm

pnpm add ws @hono/node-ws

Yarn

yarn add ws @hono/node-ws

Bun

bun add ws @hono/node-ws

備註

這些依賴套件預設並不包括在內，因為它們與 Cloudflare Workers 等無伺服器環境不兼容。如果未安裝這些依賴套件，畫面串流會停用，但所有其他瀏覽器功能仍可正常運作。

畫面串流預設為啟用，並可進行設定：

const browser = new AgentBrowser({
  screencast: {
    enabled: true,
    format: 'jpeg',
    quality: 80,
    maxWidth: 1280,
    maxHeight: 720,
  },
})

下一步

• AgentBrowser
• Stagehand
• Firecrawl
• 瀏覽器錄影（alpha）
• BrowserViewer
• MastraBrowser 參考資料
• 📹 Mastra 瀏覽器功能工作坊