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

# Firecrawl

`@mastra/browser-firecrawl` 包使用 [Firecrawl Browser Sandbox](https://docs.firecrawl.dev/features/browser) 提供浏览器自动化。它通过 Firecrawl API 配置远程浏览器会话，并使用与 [AgentBrowser](https://mastra.zisheng.pro/docs/browser/agent-browser) 相同的确定性、无障碍优先 Tool 来操控会话。

`FirecrawlBrowser` 扩展了 `AgentBrowser`，因此 Agent 可以获得相同的 Tool 集（`browser_goto`、`browser_snapshot`、`browser_click` 等），而浏览器本身运行在 Firecrawl 托管的基础设施中。无需安装本地 Chromium。

## 何时使用 Firecrawl

当你需要以下能力时，请使用 Firecrawl：

- 无需管理本地 Chromium 二进制文件的托管浏览器会话
- 在无法启动本地浏览器的环境中进行浏览器自动化
- 按线程隔离 Sandbox，并自动清理会话
- 使用具名 Firecrawl 配置文件，在会话之间保留 Cookie 和登录状态

## 快速开始

安装该包：

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

设置 Firecrawl API 密钥：

```bash
FIRECRAWL_API_KEY=fc-...
```

创建浏览器实例并将其分配给 Agent：

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

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

export const firecrawlAgent = new Agent({
  id: 'firecrawl-agent',
  name: 'Firecrawl 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`,
})
```

如果省略 `apiKey`，Provider 会从环境中读取 `FIRECRAWL_API_KEY`。

## 会话作用域

`FirecrawlBrowser` 使用与 `AgentBrowser` 相同的 `scope` 选项：

- `'thread'`（默认）：每个对话线程都有独立的 Firecrawl Sandbox 会话。线程的浏览器关闭时，会删除其会话。
- `'shared'`：所有线程共享一个 Firecrawl Sandbox 会话，并在浏览器关闭时删除该会话。

```typescript
const browser = new FirecrawlBrowser({
  scope: 'shared',
})
```

## 会话选项

在 `firecrawl` 键下传入 Firecrawl 专用的会话选项。这些选项会映射到 Firecrawl 的 `browser()` API：

```typescript
const browser = new FirecrawlBrowser({
  firecrawl: {
    ttl: 600,
    activityTtl: 120,
    profile: {
      name: 'my-profile',
      saveChanges: true,
    },
  },
})
```

- `ttl`：会话的最长生命周期（秒）。
- `activityTtl`：Firecrawl 回收会话前的空闲超时时间（秒）。
- `profile`：用于在会话之间保留 Cookie 和登录状态的具名 Firecrawl 配置文件。设置 `saveChanges: true` 可在会话结束时保存配置文件更改。

> **备注:** 嵌套的 `firecrawl.profile` 选项指存储在 Firecrawl 基础设施中的配置文件。它不同于从 `AgentBrowser` 继承的顶层 `profile` 选项；后者是本地 Playwright 用户数据目录路径。

## 自托管 Firecrawl

要使用自托管的 Firecrawl API，请设置 `apiUrl`：

```typescript
const browser = new FirecrawlBrowser({
  apiUrl: 'https://firecrawl.internal.example.com',
})
```

## 相关内容

- [Browser 概览](https://mastra.zisheng.pro/docs/browser/overview)
- [AgentBrowser](https://mastra.zisheng.pro/docs/browser/agent-browser)
- [浏览器录制（alpha）](https://mastra.zisheng.pro/docs/browser/recording)
- [FirecrawlBrowser 参考](https://mastra.zisheng.pro/reference/browser/firecrawl-browser)