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

# FirecrawlBrowser 类

`FirecrawlBrowser` 类提供由 [Firecrawl Browser Sandbox](https://docs.firecrawl.dev/features/browser) 支持的浏览器自动化。它通过 Firecrawl API 预配远程浏览器 session，并通过 Chrome DevTools Protocol（CDP）连接这些 session。

`FirecrawlBrowser` 扩展了 [`AgentBrowser`](https://mastra.zisheng.pro/reference/browser/agent-browser)，并公开相同的确定性工具集。需要托管的浏览器 session，而不是本地 Chromium 安装时，请使用它。对于本地自动化，请参阅 [`AgentBrowser`](https://mastra.zisheng.pro/reference/browser/agent-browser)。如需使用自然语言的 AI 驱动交互，请参阅 [`StagehandBrowser`](https://mastra.zisheng.pro/reference/browser/stagehand-browser)。

## 用法示例

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

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

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,
})
```

## 构造函数参数

`FirecrawlBrowser` 接受所有 [`AgentBrowser` 构造函数参数](https://mastra.zisheng.pro/reference/browser/agent-browser)，以及以下参数：

**apiKey** (`string`): Firecrawl API key。回退使用 FIRECRAWL\_API\_KEY 环境变量。如果两者均未设置，构造函数会抛出错误。

**apiUrl** (`string`): 自托管 Firecrawl API 的 base URL。

**firecrawl** (`FirecrawlBrowserSessionOptions`): 创建 Sandbox session 时传给 Firecrawl browser() API 的 session 选项。

**firecrawl.ttl** (`number`): session 的最长生命周期（秒）。

**firecrawl.activityTtl** (`number`): Sandbox 回收 session 前的空闲超时时间（秒）。

**firecrawl.streamWebView** (`boolean`): 为 true 时，Firecrawl 可能会流式传输远程 session 的 WebView 帧。

**firecrawl.profile** (`{ name: string; saveChanges?: boolean }`): 具名 Firecrawl Sandbox profile。设置 saveChanges: true，可在 session 结束时持久化 cookie 和登录状态；仅为 profile 命名不会保存更改。它与顶层 AgentBrowser profile 选项不同，后者是本地 Playwright 用户数据目录路径。

**firecrawl.integration** (`string`): 用于 Firecrawl 分析和路由的 integration 标签。

**firecrawl.origin** (`string`): Firecrawl 浏览器 session 的 origin 提示。

## Session 生命周期

Session 预配取决于从 `AgentBrowser` 继承的 `scope` 选项：

- `'thread'`（默认）：每个对话线程都有自己的 Firecrawl Sandbox session。该 session 在首次使用时创建，并在线程的浏览器 session 被销毁时删除。
- `'shared'`：浏览器启动时创建一个 Firecrawl Sandbox session，并由所有线程共享。浏览器关闭时删除该 session。

在这两种情况下，浏览器关闭时，`FirecrawlBrowser` 都会删除远程 Firecrawl session，包括 session 创建或连接中途失败的情况。

## 工具

`FirecrawlBrowser` 提供与 `AgentBrowser` 相同的工具集，包括 `browser_goto`、`browser_snapshot`、`browser_click`、`browser_type` 和 `browser_screenshot`。有关完整列表和工具参数，请参阅 [`AgentBrowser` 工具参考](https://mastra.zisheng.pro/reference/browser/agent-browser)。

## 相关内容

- [Firecrawl 文档](https://mastra.zisheng.pro/docs/browser/firecrawl)
- [`AgentBrowser` 参考](https://mastra.zisheng.pro/reference/browser/agent-browser)
- [Browser 概述](https://mastra.zisheng.pro/docs/browser/overview)