> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firecrawl.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Vercel AI SDK

> 适用于 Vercel AI SDK 的 Firecrawl 工具，为 AI 应用提供网页抓取、搜索、交互和网页爬取能力。

适用于 Vercel AI SDK 的 Firecrawl 工具，为 AI 应用提供搜索、抓取、页面交互和网页爬取能力。

<div id="install">
  ## 安装
</div>

```bash theme={null}
npm install firecrawl-aisdk ai
```

设置环境变量：

```bash theme={null}
FIRECRAWL_API_KEY=fc-your-key       # https://firecrawl.dev
AI_GATEWAY_API_KEY=your-key         # https://vercel.com/ai-gateway
```

<Note>
  这些示例使用 [Vercel AI Gateway](https://vercel.com/ai-gateway) 的 string 模型格式，但 Firecrawl 工具可以搭配任何 AI SDK 提供方使用。你也可以使用来自 `@ai-sdk/anthropic` 的提供方导入，例如 `anthropic('claude-sonnet-4-5-20250514')`。
</Note>

<div id="quick-start">
  ## 快速开始
</div>

`FirecrawlTools()` 默认集成了搜索、抓取和交互工具。

```typescript theme={null}
import { generateText, stepCountIs } from 'ai';
import { FirecrawlTools } from 'firecrawl-aisdk';

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4-5',
  tools: FirecrawlTools(),
  stopWhen: stepCountIs(30),
  prompt: `
    1. Use interact on Hacker News to identify the top story
    2. Search for other perspectives on the same topic
    3. Scrape the most relevant pages you found
    4. Summarize everything you found
  `,
});
```

<div id="firecrawltools">
  ## FirecrawlTools
</div>

`FirecrawlTools()` 会为你提供默认工具，以及一个可传给 `generateText` 的自动生成 `systemPrompt`。

```typescript theme={null}
import { generateText, stepCountIs } from 'ai';
import { FirecrawlTools } from 'firecrawl-aisdk';

const tools = FirecrawlTools();

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4-5',
  system: `${tools.systemPrompt}\n\nAnswer with citations when possible.`,
  tools,
  stopWhen: stepCountIs(20),
  prompt: 'Find the current Firecrawl pricing page and explain the available plans.',
});
```

你可以自定义默认值、按需启用异步工具，或禁用单个工具：

```typescript theme={null}
const tools = FirecrawlTools({
  search: { limit: 5 },
  scrape: { formats: ['markdown'], onlyMainContent: true },
  interact: { profile: { name: 'my-session', saveChanges: true } },
  crawl: true,
  agent: true,
});
```

```typescript theme={null}
// 禁用 interact，保留 search + scrape
FirecrawlTools({ interact: false });

// 启用已废弃的浏览器兼容性
FirecrawlTools({ browser: {} });

// 包含所有可用工具
FirecrawlTools({ all: true });
```

在通过抓取回答关于页面的问题时，使用 `question` 格式：

```typescript theme={null}
formats: [{ type: 'question', question: 'What does this page say about pricing and rate limits?' }]
```

仅在需要完整页面内容时才使用 `formats: ['markdown']`。

<div id="individual-tools">
  ## 单个工具
</div>

每个工具都可以直接使用，也可以传入选项进行调用：

```typescript theme={null}
import { generateText } from 'ai';
import { scrape, search } from 'firecrawl-aisdk';

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4-5',
  prompt: '搜索 Firecrawl，然后抓取最相关的结果。',
  tools: { search, scrape },
});

const customScrape = scrape({ apiKey: 'fc-custom-key', apiUrl: 'https://api.firecrawl.dev' });
```

<div id="search-scrape">
  ### 搜索 + 抓取
</div>

```typescript theme={null}
import { generateText } from 'ai';
import { search, scrape } from 'firecrawl-aisdk';

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4-5',
  prompt: '搜索 Firecrawl,抓取首个官方结果,并说明其功能。',
  tools: { search, scrape },
});
```

<div id="map">
  ### 映射
</div>

```typescript theme={null}
import { generateText } from 'ai';
import { map } from 'firecrawl-aisdk';

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4-5',
  prompt: 'Map https://docs.firecrawl.dev and list the main sections.',
  tools: { map },
});
```

<div id="stream">
  ### 流式
</div>

```typescript theme={null}
import { streamText, stepCountIs } from 'ai';
import { scrape } from 'firecrawl-aisdk';

const result = streamText({
  model: 'anthropic/claude-sonnet-4-5',
  prompt: 'What is the first 100 words of firecrawl.dev?',
  tools: { scrape },
  stopWhen: stepCountIs(3),
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

await result.fullStream;
```

<div id="interact">
  ## 交互
</div>

`interact()` 会创建一个由抓取驱动的交互式会话。调用 `start(url)` 以初始化会话并获取 live view URL，然后让模型通过 `interact` 工具复用该会话。

```typescript theme={null}
import { generateText, stepCountIs } from 'ai';
import { interact, search } from 'firecrawl-aisdk';

const interactTool = interact();
console.log('Live view:', await interactTool.start('https://news.ycombinator.com'));

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4-5',
  tools: { interact: interactTool, search },
  stopWhen: stepCountIs(25),
  prompt: 'Use interact on the current Hacker News session, find the top story, then search for more context.',
});

await interactTool.close();
```

如果你需要在启动后获取明确的 live view URL，请使用 `interactTool.interactiveLiveViewUrl`。

使用配置文件在不同会话间复用浏览器状态：

```typescript theme={null}
const interactTool = interact({
  profile: { name: 'my-session', saveChanges: true },
});
```

`browser()` 已弃用。建议改用 `interact()`。

<div id="async-tools">
  ## 异步工具
</div>

爬取、批量抓取 和 代理 会返回一个任务 ID。配合 `poll`。

<div id="crawl">
  ### 爬取
</div>

```typescript theme={null}
import { generateText } from 'ai';
import { crawl, poll } from 'firecrawl-aisdk';

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4-5',
  prompt: 'Crawl https://docs.firecrawl.dev (limit 3 pages) and summarize.',
  tools: { crawl, poll },
});
```

<div id="batch-scrape">
  ### 批量抓取
</div>

```typescript theme={null}
import { generateText } from 'ai';
import { batchScrape, poll } from 'firecrawl-aisdk';

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4-5',
  prompt: 'Scrape https://firecrawl.dev and https://docs.firecrawl.dev, then compare them.',
  tools: { batchScrape, poll },
});
```

<div id="agent">
  ### 代理
</div>

自动化网页数据采集，可自行搜索、浏览并提取数据。

```typescript theme={null}
import { generateText, stepCountIs } from 'ai';
import { agent, poll } from 'firecrawl-aisdk';

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4-5',
  prompt: 'Find the founders of Firecrawl, their roles, and their backgrounds.',
  tools: { agent, poll },
  stopWhen: stepCountIs(10),
});
```

<div id="logging">
  ## 日志
</div>

```typescript theme={null}
import { generateText } from 'ai';
import { logStep, scrape, stepLogger } from 'firecrawl-aisdk';

const logger = stepLogger();

const { text, usage } = await generateText({
  model: 'anthropic/claude-sonnet-4-5',
  prompt: 'Scrape https://firecrawl.dev and summarize it.',
  tools: { scrape },
  onStepFinish: logger.onStep,
  experimental_onToolCallFinish: logger.onToolCallFinish,
});

logger.close();
logger.summary(usage);

await generateText({
  model: 'anthropic/claude-sonnet-4-5',
  prompt: 'Scrape https://firecrawl.dev and summarize it again.',
  tools: { scrape },
  onStepFinish: logStep,
});
```

<div id="all-exports">
  ## 所有导出项
</div>

```typescript theme={null}
import {
  // 核心工具
  search,             // 进行网页搜索
  scrape,             // 抓取单个 URL
  map,                // 发现站点上的 URL
  crawl,              // 爬取多个页面（异步，使用 poll）
  batchScrape,        // 批量抓取多个 URL（异步，使用 poll）
  agent,              // 自主网页调研（异步，使用 poll）

  // 任务管理
  poll,               // 轮询异步任务以获取结果
  status,             // 查看任务状态
  cancel,             // 取消正在运行的任务

  // 浏览器/会话工具
  interact,           // interact({ profile: { name: '...' } })
  browser,            // 已废弃的兼容性导出

  // 一体化包
  FirecrawlTools,     // FirecrawlTools({ search, scrape, interact, crawl, agent })

  // 辅助工具
  stepLogger,         // 每次工具调用的 Token 统计
  logStep,            // 简单的单行日志记录
} from 'firecrawl-aisdk';
```