跳到主要内容

Firecrawl

@mastra/browser-firecrawl 包使用 Firecrawl Browser Sandbox 提供浏览器自动化。它通过 Firecrawl API 配置远程浏览器会话，并使用与 AgentBrowser 相同的确定性、无障碍优先 Tool 来操控会话。

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

何时使用 Firecrawl
何时使用 Firecrawl的直接链接

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

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

快速开始
快速开始的直接链接

安装该包：

npm install @mastra/browser-firecrawl

设置 Firecrawl API 密钥：

.env
FIRECRAWL_API_KEY=fc-...

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

src/mastra/agents/firecrawl-agent.ts
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 会话，并在浏览器关闭时删除该会话。
const browser = new FirecrawlBrowser({
  scope: 'shared',
})

会话选项
会话选项的直接链接

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

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的直接链接

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

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