feat: add Firecrawl search provider

[flamerged]

Target: danny-avila/agents:main
Branch: feature/firecrawl-search
Commit: f6ae68013d93310729444a2b2d99d1040f896366

Companion PR:

• Companion LibreChat PR: danny-avila/LibreChat#13262
• Companion branch: feat/firecrawl-web-search
• Companion target: dev
• Merge/publish order: merge and publish this agents package before merging the LibreChat Firecrawl plumbing PR.

Why This Matters

Firecrawl is a strong fit for agent web search because it is not just another SERP adapter. Its search API can combine web discovery with Firecrawl scraping, so agents can request search results and page content through one provider instead of wiring a separate search engine plus scraper stack.

That matters for LibreChat deployments that already want Firecrawl for AI-ready page extraction: one provider can cover the common "find sources, fetch readable content, pass clean context to the model" workflow.

References:

• Firecrawl Search API: https://docs.firecrawl.dev/api-reference/endpoint/search
• Firecrawl project overview: https://github.com/firecrawl/firecrawl

Summary

Adds Firecrawl search support to the agents search tool, including:

• v1/v2 endpoint selection
• web, image, and news source handling
• country/date filters
• scrapeOptions passthrough
• response mapping and metadata URL fallbacks
• Firecrawl-specific tool wiring
• .env.example entries for Firecrawl configuration

Tests

• npm ci: pass
• npm test -- src/tools/search/firecrawl-search.test.ts --runInBand: pass, 8 tests
• npx tsc --noEmit: pass
• npx eslint src/tools/search/search.ts src/tools/search/tool.ts src/tools/search/types.ts src/tools/search/firecrawl-search.test.ts: pass
• npm run build: pass
• git diff --check: pass
• post-amend env-doc check: pass (git diff --check, env-line format check, git show --check)

Dependency Notes

No new runtime dependency is added. The companion LibreChat PR requires a published @librechat/agents version that accepts searchProvider: "firecrawl".

Residual Risks

Coverage uses mocked axios responses, not a live Firecrawl API call.

[danny-avila]

firecrawl is already supported

[flamerged]

firecrawl is already supported

You are right that Firecrawl is already supported today as a scraper. I think this PR is a different integration point: it adds Firecrawl as a search provider using Firecrawl's /search endpoint.

I checked both main and dev, and the current upstream split is:

export type SearchProvider = 'serper' | 'searxng' | 'tavily';
export type ScraperProvider = 'firecrawl' | 'serper' | 'tavily';

createSearchAPI() also only dispatches serper, searxng, and tavily; anything else throws:

Invalid search provider: ${searchProvider}. Must be 'serper', 'searxng', or 'tavily'

And the tool docs make the same distinction:

Search providers: Serper, SearXNG, Tavily
Scraper providers: Firecrawl, Serper, Tavily

So today scraperProvider: "firecrawl" works, but searchProvider: "firecrawl" does not. This PR is intended to add the missing searchProvider: "firecrawl" path so deployments can use Firecrawl for discovery through /search, not only for scraping URLs discovered by another provider.

If you do not want Firecrawl as a search provider, that is totally fair; I just wanted to clarify that the current support is scraper support, not search-provider support.

@danny-avila

[danny-avila]

My mistake, I could've sworn we had firecrawl as a search provider since the firecrawl team itself has contributed code here. Will review as soon as I can