Building AI agents, atomically
Firecrawl Search Tool
Overview
Searches the web or recent news through the Firecrawl Search API and returns each result's title, URL, snippet, and rank, plus the publish date for news. With include_content=True the main content of each result page also comes back as Markdown in the same call, so an agent does not need a separate fetch step to read the pages. Requires a Firecrawl API key.
Prerequisites and Dependencies
- Python 3.12 or later
atomic-agentspydanticaiohttp- A Firecrawl API key from firecrawl.dev/app/api-keys, set as
FIRECRAWL_API_KEYor passed in the config
Installation
- Use the Atomic Assembler CLI: run
atomicand pickfirecrawl_search. - Or copy the
tool/folder directly into your project.
Configuration
api_key(SecretStr, a plain string is accepted): Firecrawl API key. Falls back to theFIRECRAWL_API_KEYenvironment variable when empty. It is only sent in theAuthorizationheader. Raised errors, log messages andfailuresredact the configured key (when it is at least 8 characters) and anything in Firecrawl'sfc-key format. In tracebacks that capture local variables, the key does not appear in the tool's own state or in anything derived from a response or a transport error; the inputs you pass in, such as a query, appear there as given, the same as in your own code's frames.base_url(str): API base URL (defaulthttps://api.firecrawl.dev/v2).location(str, optional): location to localise results, e.g.Germany.time_range(str, optional):day,week,month, oryear. Only applies to web results.max_content_chars(int, optional): truncate each result'scontentto this many characters. No limit by default.timeout(float): HTTP timeout in seconds (default 75, since requests withinclude_contentfetch each page).
Input & Output Structure
Input Schema
queries(list[str], at least one): search queries to run. Duplicates are sent once. Operators such assite:,"exact phrase",-term, andfiletype:pdfare supported.search_type(str):webornews. Defaultweb.max_results_per_query(int): 1-100 (default 5, kept low because each result can carry a full page withinclude_content).include_content(bool): also return each result page as Markdown (defaultFalse).
Output Schema
results: a list ofFirecrawlSearchResultItemitems. Each hasquery,title,url, and optionaldescription(a query-relevant excerpt or snippet),position,published(news), andcontent(Markdown, wheninclude_contentis set). Results without a well-formed http(s) URL (a valid host name, IPv4 or IPv6 address, a valid port, no whitespace or control characters; Unicode host names are checked in their IDNA 2003 encoded form, as Python'sidnacodec produces it) are skipped, and badly typed optional fields are left empty.failures: queries that failed while others returned results, each withqueryanderror(the HTTP status and the API's error message). Keys are redacted from both as described forapi_key. They are also logged as warnings.
Usage
If no query returns results and at least one failed (for example a wrong API key, no credits, or a malformed response), run raises the first error instead of returning an empty list. Redirects are not followed; they are reported as errors.
from tool.firecrawl_search import FirecrawlSearchTool, FirecrawlSearchToolConfig, FirecrawlSearchToolInputSchema
tool = FirecrawlSearchTool(config=FirecrawlSearchToolConfig(api_key="your-firecrawl-api-key"))
output = tool.run(FirecrawlSearchToolInputSchema(
queries=["retrieval augmented generation"],
max_results_per_query=3,
include_content=True,
))
for item in output.results:
print(item.title, "-", item.url)
print(item.content[:500] if item.content else item.description)
The request and response formats are documented at docs.firecrawl.dev/features/search.
Contributing
PRs welcome. See the main repo CONTRIBUTING.md.
License
Same as the main Atomic Agents project.