Firecrawl for Pipecat

Firecrawl web search and page reading tools for Pipecat voice agents. Maintained by Firecrawl, the company that builds and runs the Firecrawl API.

This community integration provides FirecrawlWebSearch, which gives your agent two tools:

• firecrawl_search searches the web and returns titles, URLs and snippets for the top results (Firecrawl /v2/search).
• firecrawl_scrape reads a web page and returns its main content as markdown, trimmed to a size that fits a voice turn (Firecrawl /v2/scrape).

The tool schemas carry their handlers, so passing them to an LLMContext is all the wiring you need. The LLM service registers the handlers itself.

Installation

Requires Python 3.11 or later and Pipecat 1.4 or later (below 2.0).

uv add pipecat-firecrawl

or

pip install pipecat-firecrawl

Tested with Pipecat v1.15.0. CI also runs the tests against Pipecat v1.4.0.

Usage

Get an API key at https://firecrawl.dev/app/api-keys and set FIRECRAWL_API_KEY in your environment.

import os

from pipecat.pipeline.pipeline import Pipeline
from pipecat.processors.aggregators.llm_context import LLMContext
from pipecat.processors.aggregators.llm_response_universal import LLMContextAggregatorPair

from pipecat_firecrawl import FirecrawlWebSearch

firecrawl = FirecrawlWebSearch(api_key=os.environ["FIRECRAWL_API_KEY"])

context = LLMContext(tools=firecrawl.tools())
user_aggregator, assistant_aggregator = LLMContextAggregatorPair(context)

pipeline = Pipeline(
    [
        transport.input(),
        stt,
        user_aggregator,
        llm,
        tts,
        transport.output(),
        assistant_aggregator,
    ]
)

transport, stt, llm and tts are the other parts of your application. Tell the model about the tools in its system prompt, for example "Use firecrawl_search for anything that needs current information, and firecrawl_scrape when the user gives you a URL."

To combine Firecrawl with your own tools, use firecrawl.function_schemas():

from pipecat.adapters.llm.schemas.tools_schema import ToolsSchema

tools = ToolsSchema(standard_tools=[*firecrawl.function_schemas(), my_weather_tool])
context = LLMContext(tools=tools)

You can also call Firecrawl directly, outside the LLM:

results = await firecrawl.search("latest pipecat release", limit=3)
page = await firecrawl.scrape("https://docs.pipecat.ai")

Configuration

Parameter	Default	Description
api_key	required	Your Firecrawl API key.
base_url	https://api.firecrawl.dev	API base URL. Change it for self-hosted Firecrawl.
search_limit	5	Default number of search results. The model can ask for 1 to 10.
max_page_chars	4000	Maximum characters of page markdown returned to the model.
timeout_secs	30.0	Timeout for each Firecrawl request.
aiohttp_session	None	Optional aiohttp.ClientSession to reuse across requests.

When a request fails (a bad URL, no credits, a timeout), the tool returns an error field to the model instead of raising, so the agent can tell the user what happened and keep talking.

Running the example

examples/voice_agent.py is a complete voice agent with Deepgram speech to text, an OpenAI LLM and Cartesia text to speech, running in the browser over WebRTC.

git clone https://github.com/firecrawl/pipecat-firecrawl
cd pipecat-firecrawl
cp .env.example .env   # fill in the keys
uv sync --all-extras
uv run examples/voice_agent.py

Open http://localhost:7860, click Connect and ask something like "What's on the front page of Hacker News right now?"

Development

uv sync
uv run pytest            # mocked tests; the live test runs when FIRECRAWL_API_KEY is set
uv run ruff check .
uv run ruff format --check .

License

MIT. See LICENSE.