如何5分钟上手Firecrawl Web Agent:从安装到第一次运行数据的完整教程
如何5分钟上手Firecrawl Web Agent:从安装到第一次运行数据的完整教程
🔥 Firecrawl Web Agent 是一个开源的网页数据 Agent(Web Data Agent),专为结构化网页研究(Structured Web Research)优化。它能自动完成「搜索 → 抓取 → 交互 → 分析」的闭环,把网页内容提取成 JSON、Markdown 等结构化数据。本文带你用 5 分钟走通 Web Agent 安装教程,完成从安装到第一次运行数据的全过程,无需深厚编程基础。
一、Firecrawl Web Agent 是什么?
用一句话概括:让 AI 替你上网查资料,并把结果整理成结构化数据。
Web Agent 的核心是一个「计划—行动—观察」循环:
- 计划:Agent 先拆解任务,制定研究计划
- 行动:调用网页工具执行搜索、抓取、浏览器交互
- 观察:读取工具返回的结果,决定下一步
- 循环:重复直到任务完成,最后输出结构化数据
它内置四类核心能力:
| 能力 | 说明 |
|---|---|
| 网页工具 | Search(搜索)、Scrape(抓取)、Interact(浏览器自动化)、bash(数据处理) |
| Skills | 可复用的 SKILL.md 操作手册,教会 Agent 如何访问特定网站 |
| Subagents | 并行子 Agent,多个独立任务同时跑,各自拥有独立上下文 |
| 结构化输出 | 按 JSON Schema 提取网页数据,输出 JSON 或 Markdown |
项目分为三层架构,从顶层开始就是开箱即用的应用:
| 层级 | 说明 | 创建命令 |
|---|---|---|
| Next.js 模板 | 聊天界面 + 流式输出 + 数据导出,推荐新手 | firecrawl create agent -t next |
| Express 模板 | 纯 API 服务,适合后端集成 | firecrawl create agent -t express |
| Agent Core 核心库 | 编排器、Skills、子 Agent 等底层原语 | firecrawl create agent -t library |
项目结构详见 README.md:agent-core/ 是核心 Agent 逻辑,agent-templates/ 是各套部署模板。
二、快速安装:只需 2 条命令
1. 安装 Firecrawl CLI 并认证
npx -y firecrawl-cli@latest init -y --browser
这条命令会安装 Firecrawl CLI 并通过浏览器完成账号认证,认证后即可使用你的 FIRECRAWL_API_KEY。
2. 创建你的 Agent 项目
firecrawl create agent -t next
-t next:带完整聊天界面的 Web 应用(推荐新手)-t express:纯 API 服务-t library:直接使用核心库
💡 也可以直接克隆仓库,然后在
agent-templates/next/或agent-templates/express/目录下手动运行:git clone https://gitcode.com/gh_mirrors/weba/web-agent
三、配置 API 密钥:最快配置方法
Web Agent 需要两类密钥:
FIRECRAWL_API_KEY:网页抓取服务的密钥(必填)- 模型提供商密钥:三选一,如
GOOGLE_GENERATIVE_AI_API_KEY、ANTHROPIC_API_KEY、OPENAI_API_KEY
Next.js 模板的示例文件是 .env.local.example,Express 模板是 .env.example。在各自模板目录下执行:
# Next.js 模板
cp .env.local.example .env.local # 填入你的密钥
# Express 模板
cp .env.example .env
填入密钥即可,格式示例:
FIRECRAWL_API_KEY=fc-...
GOOGLE_GENERATIVE_AI_API_KEY=AIza...
四、第一次运行:启动并获取数据
方式一:Next.js 界面版(推荐)
npm install
npm run dev
浏览器打开 http://localhost:3000,你会看到一个聊天界面。直接输入任务,例如:
帮我查询 Vercel 的定价方案,整理成表格
Agent 会实时展示研究计划、工具调用过程、并行子 Agent 进度,最后把网页数据以 JSON / Markdown 形式输出,可直接下载。
界面背后的模型与功能开关统一集中在 agent-templates/next/app/(agent)/_config.ts/_config.ts) 中,想换模型或调整行为,改这一个文件即可。
方式二:Express API 版
npm install
npm run doctor # 预检环境变量是否配置正确
npm run dev # 启动在 http://localhost:3000
用一条请求触发 Agent:
curl -X POST http://localhost:3000/v1/run \
-H "Content-Type: application/json" \
-d '{"prompt": "Get pricing for Vercel", "format": "json"}'
返回 { text, data, format, steps, usage, durationMs, model } 结构的 JSON,其中 data 就是你要的结构化数据。加上 "stream": true 还能通过 SSE 实时流式接收执行过程。各接口详情见 Express 模板 README。
五、内置 Skills:开箱即用的"网站攻略"
Web Agent 预置了多套 SKILL.md 操作手册,告诉 Agent 如何高效访问特定网站、该抓什么、如何翻页。运行时通过 skills 参数指定即可加载,例如 "skills": <a href="https://link.gitcode.com/i/58400f0590e1ec1b5fb832e3e09ffc68" target="_blank">"pricing-tracker"]。内置 Skill 一览(源码位于 [agent-core/src/skills/definitions/):
| Skill | 用途 |
|---|---|
| deep-research | 多来源深度研究 |
| e-commerce | 电商网站商品与价格抓取 |
| pricing-tracker | 定价方案跟踪 |
| financial-research | 财报、分析师数据研究 |
| competitor-analysis | 竞品分析 |
| structured-extraction | 通用结构化数据提取 |
六、常见问题排查清单
| 问题 | 解决办法 |
|---|---|
Unknown name "const" 400 错误 |
Gemini 拒绝了含 const 字段的工具 Schema,换一个模型或提供商即可 |
ANTHROPIC_API_KEY not set |
检查环境变量,或运行 npm run doctor 预检 |
prompt is required |
确保 prompt 传了非空字符串 |
| LangChain 相关包缺失 | 按所用提供商安装,如 npm i @langchain/anthropic |
更完整的排查清单见 agent-core/README.md。
七、上手之后:推荐的下一步
- 用 JSON Schema 约束输出结构:agent-core/examples/2-structured-output.ts
- 并行子 Agent 同时查多个网站:agent-core/examples/3-parallel-subagents.ts
- 最小示例(单条 prompt 即可运行):agent-core/examples/1-basic.ts
- 把一次成功运行导出为可复用的 Skill,下次直接重放整个工作流
恭喜你,现在已经拥有一个能自主上网做结构化研究的网页数据 Agent 了,祝挖掘愉快 🚀
