> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# Browser 概览

Browser 支持让 Agent 能够浏览网站、与页面元素交互、填写表单并提取数据。Mastra 通过封装浏览器自动化库的 SDK Provider，以及供 Agent 通过命令行 Tool 操控浏览器的 CLI Provider 来提供浏览器功能。

Mastra 支持三个 SDK Provider 和一个 CLI Provider：

- [**AgentBrowser**](https://mastra.zisheng.pro/docs/browser/agent-browser)：基于 Playwright 的 Provider，优先通过无障碍信息定位元素。最适合常规网页自动化和抓取。
- [**Stagehand**](https://mastra.zisheng.pro/docs/browser/stagehand)：使用 AI 驱动元素检测的 Browserbase Provider。最适合能从自然语言选择器中获益的复杂交互。
- [**FirecrawlBrowser**](https://mastra.zisheng.pro/docs/browser/firecrawl)：Firecrawl Browser Sandbox Provider，针对托管浏览器会话运行 AgentBrowser Tool。最适合无需管理本地浏览器基础设施即可在托管浏览器会话中运行自动化。
- [**BrowserViewer**](https://mastra.zisheng.pro/docs/browser/browser-viewer)：启动 Chrome 并将 CDP URL 注入 agent-browser、browser-use 和 browse 等 CLI Tool 的 CLI Provider。最适合通过 shell 命令操控浏览器的 Workspace Agent。
- [**浏览器录制（alpha）**](https://mastra.zisheng.pro/docs/browser/recording)：可选择启用的 Tool 层，将浏览器会话保存为 Motion-JPEG AVI 视频，并可添加字幕。

## 何时使用 Browser

当 Agent 需要执行以下操作时，请使用 Browser：

- 浏览网站并与页面元素交互
- 填写表单并提交数据
- 从网页提取结构化数据
- 自动执行多步骤网页 Workflow
- 执行需要真实浏览器的操作（JavaScript 渲染、身份验证流程）

## 工作原理

为 Agent 分配 Browser 后，Mastra 会将 Provider 的 Tool 添加到 Agent 的 Tool 集中。Agent 使用这些 Tool 控制浏览器：导航到 URL、选择元素、输入文本以及读取页面内容。

每个 Provider 都会提供一组针对自身实现方式优化的不同 Tool。

## 快速开始

安装所选的 Provider。本示例使用 AgentBrowser Provider。

**npm**:

```bash
npm install @mastra/agent-browser
```

**pnpm**:

```bash
pnpm add @mastra/agent-browser
```

**Yarn**:

```bash
yarn add @mastra/agent-browser
```

**Bun**:

```bash
bun add @mastra/agent-browser
```

创建新的浏览器实例：

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

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

将 Browser 分配给 Agent：

```typescript
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 提供的所有 Browser Tool。

## 云 Provider

所有 SDK Provider 都支持连接云浏览器服务，而不是启动本地浏览器。

### Firecrawl Browser Sandbox（FirecrawlBrowser 原生支持）

FirecrawlBrowser 通过 Firecrawl API 配置托管会话：

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

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

### Browserbase（Stagehand 原生支持）

Stagehand 原生集成 Browserbase：

```typescript
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）端点的浏览器：

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

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

这适用于任何[兼容 CDP](https://chromedevtools.github.io/devtools-protocol/) 的浏览器服务。

## 投屏

Browser Provider 会向 Mastra Studio UI 实时传输浏览器的视频画面。你可以借此实时观察 Agent 与页面交互。

投屏需要 WebSocket 支持。请在项目中安装以下包：

**npm**:

```bash
npm install ws @hono/node-ws
```

**pnpm**:

```bash
pnpm add ws @hono/node-ws
```

**Yarn**:

```bash
yarn add ws @hono/node-ws
```

**Bun**:

```bash
bun add ws @hono/node-ws
```

> **备注:** 默认不包含这些包，因为它们与 Cloudflare Workers 等无服务器环境不兼容。如果未安装这些包，投屏功能会被禁用，但其他所有 Browser 功能仍可正常工作。

投屏默认启用，可以进行配置：

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

## 后续步骤

- [AgentBrowser](https://mastra.zisheng.pro/docs/browser/agent-browser)
- [Stagehand](https://mastra.zisheng.pro/docs/browser/stagehand)
- [Firecrawl](https://mastra.zisheng.pro/docs/browser/firecrawl)
- [浏览器录制（alpha）](https://mastra.zisheng.pro/docs/browser/recording)
- [BrowserViewer](https://mastra.zisheng.pro/docs/browser/browser-viewer)
- [MastraBrowser 参考](https://mastra.zisheng.pro/reference/browser/mastra-browser)
- 📹 [Mastra Browser 功能研讨会](https://www.youtube.com/watch?v=E9KFsZEnQO8\&t=5s)