#1433 feat(examples): add with-firecrawl-search

Hey, I'm Juampi from the Firecrawl team. Thanks for VoltAgent and for keeping the examples folder open to integrations. This PR adds a small Firecrawl example.

PR Checklist

Please check if your PR fulfills the following requirements:

• The commit message follows our guidelines: https://voltagent.dev/docs/community/contributing/#commit-convention

Bugs / Features

• Related issue(s) linked
• Tests for the changes have been added
• Docs have been added / updated
• Changesets have been added https://voltagent.dev/docs/community/contributing/#creating-a-changeset

What is the current behavior?

There is no Firecrawl example in examples/.

What is the new behavior?

examples/with-firecrawl-search is a research agent with two tools:

• firecrawlSearch searches the web and returns titles, URLs and descriptions. It can also return each result's page as Markdown in the same call (scrapeContent: true).
• firecrawlScrape fetches any URL as clean Markdown.

The agent searches first, reads the one or two most relevant pages when the descriptions are not enough, and cites the URLs it used. It follows the layout of the other web search example, uses fetch against the Firecrawl v2 API (no new dependencies), and adds one line to examples/README.md plus the lockfile importer entry for the new package.

Notes for reviewers

How I tested it, with gpt-4o-mini against the published @voltagent/* packages, calling POST /agents/Web%20Research%20Agent/text:

1. "What is the current Node.js LTS release line and when does it reach end of life? Cite your sources." The agent called firecrawlSearch, then firecrawlScrape on two of the results, and answered with Node.js 24 and 22 and their end-of-life dates, citing both pages.
2. "Give me three links to introductions to the Model Context Protocol, with one sentence on what each covers." The agent called firecrawlSearch only and answered with three cited links.

I also called both tools directly with scrapeContent: true, a missing key, an invalid key (401) and an invalid URL (400). Each error returns a { success: false, error, message } result instead of throwing. tsc (the example's build script), biome check examples/with-firecrawl-search and Prettier on both READMEs pass. No changeset, since examples are not published.

If a recipe page on voltagent.dev would help, I'm happy to write one.

---

Summary by cubic

Adds examples/with-firecrawl-search, a research agent that searches the web and reads pages as clean Markdown with Firecrawl.

• Provides two tools: firecrawlSearch returns titles, URLs, and descriptions with optional Markdown, and firecrawlScrape fetches any URL as Markdown.
• Uses fetch against the Firecrawl v2 API with no new dependencies, serializing request bodies with safeStringify.
• Applies a 120-second request timeout and keeps page content context-safe by truncating long output, configurable via constants in src/tools.ts.
• Returns structured { success: false, error, message } results on API errors instead of throwing, and surfaces invalid JSON responses as errors.
• Uses NodeNext module resolution with .js import paths for Node ESM compatibility.
• Adds the example to examples/README.md and registers it in the lockfile.

Summary by CodeRabbit

• New Features
  • Added a Firecrawl Search example for web research, with tools to search the web and read relevant pages as Markdown. The example can cite sources and report tool errors.
  • Search returns five results by default, up to ten; search and scraped-page Markdown have content limits.
• Documentation
  • Added setup guidance, API key configuration, tool parameters, content limits, and troubleshooting information for the example.