Firecrawl 于 2026-09-28 发布 firecrawl-py 4.45.0 与 @mendable/firecrawl-js 4.42.0，把此前合并的 agent_hints（#4641）真正打进 SDK：在请求头 X-Firecrawl-Agent-Hints: true 时，Search/Scrape/Parse/Map 响应可附带确定性下一步建议（如空结果改查询、同源多 URL 建议 Map/Crawl、401 建议 Interact、截断 PDF 提高 maxPages、余额不足提示用户充值）。同期带上 Hangar 上的 browser/interact 迁移与 exchange.onTermsRequired 字段。

核心要点速览 (Key Takeaways)

  • ✓SDK：firecrawl-py 4.45.0 / @mendable/firecrawl-js 4.42.0（2026-09-28，#4786）
  • ✓协议：可选头 X-Firecrawl-Agent-Hints: true 才注入 hints；默认关闭，避免破坏普通 HTTP 调用（#4641）
  • ✓规则示例：空 web 结果→建议改 Search；≥4 条且 ≥75% 同源→建议 Map/Crawl；401+scrapeId→Interact；截断 PDF→提高 maxPages（上限 10000）；余额 <100 credits→提示充值
  • ✓MCP：firecrawl-mcp-server 仍钉 [email protected]，需再 bump 才能在 map/错误归一化路径保留 hints
  • ✓文档：Search / Python SDK / 仓库
🧭

阅读完核心要点？进一步了解模型实力与实际开销

7 大权威镜像天梯跑分与 29+ 款主流编程套餐横向比价测算

🏆 天梯榜(72s必看)→💰 比价测算↗
🔗

相关资源与官方项目出处

免代理直达
💡 国内无需访问 Twitter，可直接访问上述项目官方资源与文档
🐙
PR #4786 SDK bump for agent hints
github.com/firecrawl/firecrawl/pull/4786
↗
🐙
PR #4641 agent_hints API feature
github.com/firecrawl/firecrawl/pull/4641
↗
🐙
firecrawl/firecrawl repository
github.com/firecrawl/firecrawl
↗
📖
Firecrawl Search docs
docs.firecrawl.dev/features/search
↗
🌐
PyPI firecrawl-py 4.45.0
pypi.org/project/firecrawl-py/4.45.0/
↗
🌐
npm @mendable/firecrawl-js
www.npmjs.com/package/@mendable/firecrawl-js
↗
📖
Python SDK 文档
docs.firecrawl.dev/sdks/python
↗
🔬

深度技术解析与实战评估

核心背景与行业痛点

智能体调用网页 Search/Scrape 后常陷入「拿到结果却不知下一步」：空结果不会自动换查询，同源多链不会升级成 Map/Crawl，401 页面不会想到 Interact，PDF 截断也不会提高 maxPages。缺少响应级、可机器执行的下一步提示时，代理只能靠脆弱 prompt 猜测，链路失败率与无效调用成本都会上升。

架构亮点与底层机制

API 侧 #4641 为 v2 Search/Scrape/Parse/Map 增加可选顶层 agent_hints: string[]；仅当请求带 X-Firecrawl-Agent-Hints: true 时注入，默认关闭以免破坏普通 HTTP 调用。规则含：含摘要的 Search 可建议 Scrape；空 web 结果建议改查询；≥4 条且 ≥75% 同源建议 Map/Crawl；401+scrapeId 建议 Interact；截断 PDF（totalPages > numPages）建议提高 maxPages（上限 10000）；余额 <100 credits 时提示用户充值。SDK #4786 把上述字段保留进 Python 4.45.0 / JS 4.42.0，并带上 Hangar browser/interact 与 onTermsRequired。

权威 Benchmark 与实测跑分对比

本 SDK 发版未附带新的 arXivQA 或 Agent Score 表。文档站 Search 引用第三方 Agentic Search Benchmark（截至来源页更新）Agent Score 均值 14.58、8 家中排第 2（n=100），属独立评测非本版专测。请以自有代理任务验收 hints 是否触发，以及 MCP 钉版本是否丢字段。

开发者实战落地与开箱指南

升级：pip install -U firecrawl-py==4.45.0 或 npm i @mendable/[email protected]（见 PyPI）。代理与 MCP 路径设置 X-Firecrawl-Agent-Hints: true；若用官方 MCP，需将 firecrawl 钉从 4.40.0 升到 ≥4.42.0 才能在 map/错误归一化路径保留 hints。用法见 Python SDK 文档 与 Search 文档。