Skip to content

Building AI agents, atomically

Add Firecrawl Search tool to the Atomic Forge

Juampi160100897917
diff --git a/AGENTS.md b/AGENTS.md
index ac320a4..688aa82 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -100,6 +100,7 @@ Each example is self-contained and demonstrates specific patterns and capabiliti
- `calculator/` - Mathematical computation tool
- `datetime_tool/` - Timezone-aware now / parse / convert / shift / diff
- `fia_signals/` - Crypto market intelligence (regime, signals, yields, gas, trending, wallet risk)
+- `firecrawl_search/` - Web and news search via the Firecrawl API, with optional page content as Markdown
- `hackernews_search/` - Hacker News search via the free Algolia API
- `pdf_reader/` - PDF text + metadata extraction (local file or URL, page-range support)
- `searxng_search/` - Privacy-focused search integration
diff --git a/README.md b/README.md
index 270f558..eaa6a16 100644
--- a/README.md
+++ b/README.md
@@ -349,6 +349,7 @@ Atomic Forge is a collection of tools that can be used with Atomic Agents to ext
- Calculator
- DateTime
- Fía Signals
+- Firecrawl Search
- Hacker News Search
- PDF Reader
- SearXNG Search
diff --git a/atomic-forge/README.md b/atomic-forge/README.md
index d34c5a0..1930426 100644
--- a/atomic-forge/README.md
+++ b/atomic-forge/README.md
@@ -18,6 +18,7 @@ The Atomic Forge project includes the following tools:
- [Calculator](/atomic-forge/tools/calculator/README.md)
- [DateTime](/atomic-forge/tools/datetime_tool/README.md) — timezone-aware now/parse/convert/shift/diff.
- [Fía Signals](/atomic-forge/tools/fia_signals/README.md)
+- [Firecrawl Search](/atomic-forge/tools/firecrawl_search/README.md) — web and news search via the Firecrawl API, with optional page content as Markdown.
- [Hacker News Search](/atomic-forge/tools/hackernews_search/README.md) — search HN stories, comments, Show HN, Ask HN via the free Algolia API.
- [PDF Reader](/atomic-forge/tools/pdf_reader/README.md) — extract text and metadata from a local or remote PDF, with page-range filtering.
- [SearXNG Search](/atomic-forge/tools/searxng_search/README.md)
diff --git a/atomic-forge/tools/firecrawl_search/.coveragerc b/atomic-forge/tools/firecrawl_search/.coveragerc
new file mode 100644
index 0000000..c45136e
--- /dev/null
+++ b/atomic-forge/tools/firecrawl_search/.coveragerc
@@ -0,0 +1,8 @@
+[run]
+source = tool
+omit = */tests/*
+
+[report]
+exclude_lines =
+ if __name__ == "__main__":
+show_missing = True
diff --git a/atomic-forge/tools/firecrawl_search/README.md b/atomic-forge/tools/firecrawl_search/README.md
new file mode 100644
index 0000000..74b1782
--- /dev/null
+++ b/atomic-forge/tools/firecrawl_search/README.md
@@ -0,0 +1,61 @@
+# Firecrawl Search Tool
+
+## Overview
+Searches the web or recent news through the [Firecrawl Search](https://www.firecrawl.dev/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-agents`
+- `pydantic`
+- `aiohttp`
+- A Firecrawl API key from [firecrawl.dev/app/api-keys](https://www.firecrawl.dev/app/api-keys), set as `FIRECRAWL_API_KEY` or passed in the config
+
+## Installation
+1. Use the Atomic Assembler CLI: run `atomic` and pick `firecrawl_search`.
+2. Or copy the `tool/` folder directly into your project.
+
+## Configuration
+- `api_key` (str): Firecrawl API key. Falls back to the `FIRECRAWL_API_KEY` environment variable when empty.
+- `base_url` (str): API base URL (default `https://api.firecrawl.dev/v2`).
+- `location` (str, optional): location to localise results, e.g. `Germany`.
+- `time_range` (str, optional): `day`, `week`, `month`, or `year`. Only applies to web results.
+- `max_content_chars` (int, optional): truncate each result's `content` to this many characters. No limit by default.
+- `timeout` (float): HTTP timeout in seconds (default 75, since requests with `include_content` fetch each page).
+
+## Input & Output Structure
+
+### Input Schema
+- `queries` (list[str]): search queries to run. Operators such as `site:`, `"exact phrase"`, `-term`, and `filetype:pdf` are supported.
+- `search_type` (str): `web` or `news`. Default `web`.
+- `max_results_per_query` (int): 1-100 (default 5, kept low because each result can carry a full page with `include_content`).
+- `include_content` (bool): also return each result page as Markdown (default `False`).
+
+### Output Schema
+A list of `FirecrawlSearchResultItem` items. Each has `query`, `title`, `url`, and optional `description` (a query-relevant excerpt or snippet), `position`, `published` (news), and `content` (Markdown, when `include_content` is set).
+
+## Usage
+If every query fails (for example a wrong API key), `run` raises the error. If only some fail, the others are returned and the failures are logged.
+
+```python
+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](https://docs.firecrawl.dev/features/search).
+
+## Contributing
+PRs welcome. See the main repo `CONTRIBUTING.md`.
+
+## License
+Same as the main Atomic Agents project.
diff --git a/atomic-forge/tools/firecrawl_search/pyproject.toml b/atomic-forge/tools/firecrawl_search/pyproject.toml
new file mode 100644
index 0000000..efdc59a
--- /dev/null
+++ b/atomic-forge/tools/firecrawl_search/pyproject.toml
@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["tool"]
+
+[project]
+name = "firecrawl-search"
+version = "1.0.0"
+description = "Web and news search for Atomic Agents via the Firecrawl Search API, with optional page content"
+readme = "README.md"
+authors = [
+ { name = "Juampi (Firecrawl)", email = "[email protected]" }
+]
+requires-python = ">=3.12"
+dependencies = [
+ "atomic-agents",
+ "pydantic>=2.10.3,<3.0.0",
+ "aiohttp>=3.9.0,<4.0.0",
+]
+
+[dependency-groups]
+dev = [
+ "coverage>=7.6.1,<8.0.0",
+ "pytest>=8.3.3,<9.0.0",
+ "pytest-asyncio>=0.23.5,<1.0.0",
+ "pytest-cov>=5.0.0,<6.0.0",
+ "python-dotenv>=1.0.0,<2.0.0",
+ "rich>=13.7.0,<14.0.0",
+]
+
+[tool.uv.sources]
+atomic-agents = { workspace = true }
diff --git a/atomic-forge/tools/firecrawl_search/requirements.txt b/atomic-forge/tools/firecrawl_search/requirements.txt
new file mode 100644
index 0000000..469c7e9
--- /dev/null
+++ b/atomic-forge/tools/firecrawl_search/requirements.txt
@@ -0,0 +1,3 @@
+atomic-agents>=2.0.0,<3.0.0
+pydantic>=2.10.3,<3.0.0
+aiohttp>=3.9.0,<4.0.0
diff --git a/atomic-forge/tools/firecrawl_search/tests/test_firecrawl_search.py b/atomic-forge/tools/firecrawl_search/tests/test_firecrawl_search.py
new file mode 100644
index 0000000..2c78168
--- /dev/null
+++ b/atomic-forge/tools/firecrawl_search/tests/test_firecrawl_search.py
@@ -0,0 +1,317 @@
+import os
+import sys
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
+
+from tool.firecrawl_search import ( # noqa: E402
+ FirecrawlSearchResultItem,
+ FirecrawlSearchTool,
+ FirecrawlSearchToolConfig,
+ FirecrawlSearchToolInputSchema,
+ FirecrawlSearchToolOutputSchema,
+)
+
+
+WEB_HIT = {
+ "url": "https://www.python.org/",
+ "title": "Welcome to Python.org",
+ "description": "Python is a programming language that lets you work quickly.",
+ "position": 1,
+}
+
+NEWS_HIT = {
+ "url": "https://example.com/python-3-14",
+ "title": "Python 3.14 released",
+ "snippet": "The Python core team shipped 3.14 today.",
+ "date": "2 days ago",
+ "imageUrl": "https://example.com/thumb.png",
+ "position": 2,
+}
+
+CONTENT_HIT = {
+ "url": "https://example.com/guide",
+ "description": "A guide to agents.",
+ "position": 3,
+ "markdown": "# Agent guide\n\nBuild agents step by step.",
+ "metadata": {"title": "Agent guide | Example", "description": "Metadata description", "statusCode": 200},
+}
+
+
+def _mock_session(status: int, payload: dict, reason: str = "OK") -> MagicMock:
+ session = MagicMock()
+ response = SimpleNamespace(status=status, reason=reason, json=AsyncMock(return_value=payload))
+ session.post.return_value.__aenter__.return_value = response
+ return session
+
+
+def tool():
+ return FirecrawlSearchTool(config=FirecrawlSearchToolConfig(api_key="test-key"))
+
+
+def test_to_item_web():
+ item = FirecrawlSearchTool._to_item(WEB_HIT, "python")
+ assert isinstance(item, FirecrawlSearchResultItem)
+ assert item.query == "python"
+ assert item.title == "Welcome to Python.org"
+ assert item.url == "https://www.python.org/"
+ assert item.description.startswith("Python is a programming language")
+ assert item.position == 1
+ assert item.published is None
+ assert item.content is None
+
+
+def test_to_item_news():
+ """News results carry a snippet and a relative date instead of a description."""
+ item = FirecrawlSearchTool._to_item(NEWS_HIT, "python")
+ assert item.description == "The Python core team shipped 3.14 today."
+ assert item.published == "2 days ago"
+ assert item.position == 2
+
+
+def test_to_item_with_content():
+ """With scrapeOptions each result carries markdown and page metadata."""
+ item = FirecrawlSearchTool._to_item(CONTENT_HIT, "agents")
+ assert item.title == "Agent guide | Example"
+ assert item.description == "A guide to agents."
+ assert item.content.startswith("# Agent guide")
+
+
+def test_to_item_falls_back_to_url_for_title():
+ item = FirecrawlSearchTool._to_item({"url": "https://example.com/untitled"}, "q")
+ assert item.title == "https://example.com/untitled"
+ assert item.description is None
+
+
+def test_build_body_defaults(tool):
+ body = tool._build_body("python", FirecrawlSearchToolInputSchema(queries=["python"]))
+ assert body == {"query": "python", "limit": 5, "sources": ["web"], "origin": "atomic-agents"}
+
+
+def test_build_body_with_options():
+ tool = FirecrawlSearchTool(config=FirecrawlSearchToolConfig(api_key="k", location="Germany", time_range="week"))
+ params = FirecrawlSearchToolInputSchema(queries=["python"], max_results_per_query=3, include_content=True)
+
+ body = tool._build_body("python", params)
+
+ assert body["sources"] == ["web"]
+ assert body["limit"] == 3
+ assert body["location"] == "Germany"
+ assert body["tbs"] == "qdr:w"
+ assert body["scrapeOptions"] == {"formats": ["markdown"], "onlyMainContent": True}
+
+
+def test_build_body_skips_time_range_for_news():
+ """The API's tbs filter only applies to web results."""
+ tool = FirecrawlSearchTool(config=FirecrawlSearchToolConfig(api_key="k", time_range="day"))
+
+ body = tool._build_body("python", FirecrawlSearchToolInputSchema(queries=["python"], search_type="news"))
+
+ assert body["sources"] == ["news"]
+ assert "tbs" not in body
+
+
+def test_to_item_truncates_content_and_ignores_bad_metadata():
+ hit = {**CONTENT_HIT, "metadata": ["not", "a", "dict"]}
+
+ item = FirecrawlSearchTool._to_item(hit, "agents", max_content_chars=7)
+
+ assert item.content == "# Agent"
+ assert item.title == "https://example.com/guide"
+
+
+async def test_fetch_builds_request(tool):
+ session = _mock_session(200, {"success": True, "data": {"web": [WEB_HIT]}})
+ params = FirecrawlSearchToolInputSchema(queries=["python"])
+
+ items = await tool._fetch(session, "python", params)
+
+ assert len(items) == 1
+ assert items[0].url == "https://www.python.org/"
+ call_args = session.post.call_args
+ assert call_args[0][0] == "https://api.firecrawl.dev/v2/search"
+ assert call_args[1]["json"]["query"] == "python"
+
+
+async def test_fetch_reads_news_results(tool):
+ session = _mock_session(200, {"success": True, "data": {"news": [NEWS_HIT] * 4}})
+ params = FirecrawlSearchToolInputSchema(queries=["python"], search_type="news", max_results_per_query=2)
+
+ items = await tool._fetch(session, "python", params)
+
+ assert len(items) == 2
+ assert items[0].published == "2 days ago"
+
+
+async def test_fetch_handles_missing_source_key(tool):
+ """The API omits the source key entirely when there are no results."""
+ session = _mock_session(200, {"success": True, "data": {}})
+
+ items = await tool._fetch(session, "nothing", FirecrawlSearchToolInputSchema(queries=["nothing"]))
+
+ assert items == []
+
+
+async def test_fetch_skips_hits_without_url(tool):
+ session = _mock_session(200, {"success": True, "data": {"web": [WEB_HIT, {"title": "no url"}]}})
+
+ items = await tool._fetch(session, "python", FirecrawlSearchToolInputSchema(queries=["python"]))
+
+ assert [item.url for item in items] == ["https://www.python.org/"]
+
+
+async def test_fetch_raises_on_http_error(tool):
+ session = _mock_session(401, {"success": False, "error": "Unauthorized: Invalid token"}, reason="Unauthorized")
+
+ with pytest.raises(Exception, match="Firecrawl search failed for 'python': 401 Unauthorized: Invalid token"):
+ await tool._fetch(session, "python", FirecrawlSearchToolInputSchema(queries=["python"]))
+
+
+async def test_fetch_raises_when_success_is_false(tool):
+ session = _mock_session(200, {"success": False})
+
+ with pytest.raises(Exception, match="Firecrawl search failed for 'python': 200 OK"):
+ await tool._fetch(session, "python", FirecrawlSearchToolInputSchema(queries=["python"]))
+
+
+async def test_fetch_reports_status_for_non_json_body(tool):
+ session = MagicMock()
+ response = SimpleNamespace(status=502, reason="Bad Gateway", json=AsyncMock(side_effect=ValueError("not json")))
+ session.post.return_value.__aenter__.return_value = response
+
+ with pytest.raises(Exception, match="Firecrawl search failed for 'python': 502 Bad Gateway"):
+ await tool._fetch(session, "python", FirecrawlSearchToolInputSchema(queries=["python"]))
+
+
+async def test_fetch_applies_max_content_chars():
+ tool = FirecrawlSearchTool(config=FirecrawlSearchToolConfig(api_key="k", max_content_chars=5))
+ session = _mock_session(200, {"success": True, "data": {"web": [CONTENT_HIT, "not a dict"]}})
+
+ items = await tool._fetch(session, "agents", FirecrawlSearchToolInputSchema(queries=["agents"], include_content=True))
+
+ assert [item.content for item in items] == ["# Age"]
+
+
+async def test_run_async_aggregates_results(tool):
+ async def fake_fetch(self, session, query, params):
+ return [FirecrawlSearchTool._to_item(WEB_HIT, query), FirecrawlSearchTool._to_item(NEWS_HIT, query)]
+
+ with patch.object(FirecrawlSearchTool, "_fetch", fake_fetch):
+ out = await tool.run_async(FirecrawlSearchToolInputSchema(queries=["q1", "q2"]))
+
+ assert isinstance(out, FirecrawlSearchToolOutputSchema)
+ assert len(out.results) == 4
+ assert {r.query for r in out.results} == {"q1", "q2"}
+
+
+async def test_run_async_skips_failing_query(tool):
+ async def fake_fetch(self, session, query, params):
+ if query == "bad":
+ raise Exception("rate limited")
+ return [FirecrawlSearchTool._to_item(WEB_HIT, query)]
+
+ with patch.object(FirecrawlSearchTool, "_fetch", fake_fetch):
+ out = await tool.run_async(FirecrawlSearchToolInputSchema(queries=["bad", "good"]))
+
+ assert len(out.results) == 1
+ assert out.results[0].query == "good"
+
+
+async def test_run_async_raises_when_every_query_fails(tool):
+ """A bad key or exhausted credits should surface as an error, not as an empty result."""
+
+ async def fake_fetch(self, session, query, params):
+ raise Exception("Firecrawl search failed for 'q': 401 Unauthorized: Invalid token")
+
+ with patch.object(FirecrawlSearchTool, "_fetch", fake_fetch):
+ with pytest.raises(Exception, match="401"):
+ await tool.run_async(FirecrawlSearchToolInputSchema(queries=["q1", "q2"]))
+
+
+async def test_run_async_end_to_end_with_mocked_session(tool):
+ session = _mock_session(200, {"success": True, "data": {"web": [WEB_HIT]}})
+
+ class FakeSession:
+ def __init__(self, headers=None, timeout=None):
+ self.headers = headers
+
+ async def __aenter__(self):
+ return session
+
+ async def __aexit__(self, *args):
+ return False
+
+ with patch("tool.firecrawl_search.aiohttp.ClientSession", FakeSession):
+ out = await tool.run_async(FirecrawlSearchToolInputSchema(queries=["python"], include_content=True))
+
+ assert [r.url for r in out.results] == ["https://www.python.org/"]
+ assert session.post.call_args[1]["json"]["scrapeOptions"]["formats"] == ["markdown"]
+
+
+async def test_run_async_sends_bearer_header(tool):
+ captured = {}
+
+ class FakeSession:
+ def __init__(self, headers=None, timeout=None):
+ captured["headers"] = headers
+
+ async def __aenter__(self):
+ return self
+
+ async def __aexit__(self, *args):
+ return False
+
+ async def fake_fetch(self, session, query, params):
+ return []
+
+ with (
+ patch("tool.firecrawl_search.aiohttp.ClientSession", FakeSession),
+ patch.object(FirecrawlSearchTool, "_fetch", fake_fetch),
+ ):
+ await tool.run_async(FirecrawlSearchToolInputSchema(queries=["q"]))
+
+ assert captured["headers"]["Authorization"] == "Bearer test-key"
+ assert captured["headers"]["Content-Type"] == "application/json"
+
+
+async def test_run_async_requires_api_key(monkeypatch):
+ monkeypatch.delenv("FIRECRAWL_API_KEY", raising=False)
+ tool = FirecrawlSearchTool(config=FirecrawlSearchToolConfig())
+
+ with pytest.raises(ValueError, match="FIRECRAWL_API_KEY"):
+ await tool.run_async(FirecrawlSearchToolInputSchema(queries=["q"]))
+
+
+def test_api_key_falls_back_to_environment(monkeypatch):
+ monkeypatch.setenv("FIRECRAWL_API_KEY", "env-key")
+ tool = FirecrawlSearchTool(config=FirecrawlSearchToolConfig())
+ assert tool.api_key == "env-key"
+
+
+def test_run_invokes_run_async(tool):
+ sentinel = FirecrawlSearchToolOutputSchema(results=[])
+ with patch.object(FirecrawlSearchTool, "run_async", AsyncMock(return_value=sentinel)):
+ out = tool.run(FirecrawlSearchToolInputSchema(queries=["x"]))
+ assert out is sentinel
+
+
+if __name__ == "__main__":
+ pytest.main([__file__, "-v"])
diff --git a/atomic-forge/tools/firecrawl_search/tool/firecrawl_search.py b/atomic-forge/tools/firecrawl_search/tool/firecrawl_search.py
new file mode 100644
index 0000000..4ee7a66
--- /dev/null
+++ b/atomic-forge/tools/firecrawl_search/tool/firecrawl_search.py
@@ -0,0 +1,220 @@
+import asyncio
+import logging
+import os
+from concurrent.futures import ThreadPoolExecutor
+from typing import List, Literal, Optional
+
+import aiohttp
+from pydantic import Field
+
+from atomic_agents import BaseIOSchema, BaseTool, BaseToolConfig
+
+
+logger = logging.getLogger(__name__)
+
+
+################
+# INPUT SCHEMA #
+################
+class FirecrawlSearchToolInputSchema(BaseIOSchema):
+ """
+ Search the web or recent news through the Firecrawl Search API.
+ Use this to find current information on a topic. Set include_content to true to also get
+ each result page as Markdown in the same call. Requires a Firecrawl API key.
+ """
+
+ queries: List[str] = Field(
+ ...,
+ description='Search queries to run. Supports operators such as site:, "exact phrase", -term, and filetype:pdf.',
+ )
+ search_type: Literal["web", "news"] = Field(
+ default="web",
+ description="Which results to return. 'web' = web pages; 'news' = news articles.",
+ )
+ max_results_per_query: int = Field(default=5, ge=1, le=100, description="Maximum results per query.")
+ include_content: bool = Field(
+ default=False,
+ description="Also return the main content of each result page as Markdown. Slower than a plain search.",
+ )
+
+
+####################
+# OUTPUT SCHEMA(S) #
+####################
+class FirecrawlSearchResultItem(BaseIOSchema):
+ """A single Firecrawl search result (web page or news article)."""
+
+ query: str = Field(..., description="The query that produced this result.")
+ title: str = Field(..., description="Title of the result.")
+ url: str = Field(..., description="URL of the result.")
+ description: Optional[str] = Field(None, description="Query-relevant excerpt or snippet for the result.")
+ position: Optional[int] = Field(None, description="Rank of the result.")
+ published: Optional[str] = Field(None, description="Publication date string (news only).")
+ content: Optional[str] = Field(None, description="Page content as Markdown (only when include_content is set).")
+
+
+class FirecrawlSearchToolOutputSchema(BaseIOSchema):
+ """Output of the Firecrawl search tool."""
+
+ results: List[FirecrawlSearchResultItem] = Field(..., description="Matching results across all queries.")
+
+
+#################
+# CONFIGURATION #
+#################
+class FirecrawlSearchToolConfig(BaseToolConfig):
+ """Configuration for the FirecrawlSearchTool."""
+
+ api_key: str = Field(
+ default="", description="Firecrawl API key. Falls back to the FIRECRAWL_API_KEY environment variable."
+ )
+ base_url: str = Field(default="https://api.firecrawl.dev/v2", description="Firecrawl API base URL.")
+ location: Optional[str] = Field(
+ default=None, description="Location to localise results, e.g. 'Germany' or 'San Francisco,California,United States'."
+ )
+ time_range: Optional[Literal["day", "week", "month", "year"]] = Field(
+ default=None, description="Only return web results from this time window. Does not apply to news."
+ )
+ max_content_chars: Optional[int] = Field(
+ default=None, ge=1, description="Truncate each result's content to this many characters. No limit when unset."
+ )
+ timeout: float = Field(default=75.0, ge=1.0, le=120.0, description="HTTP request timeout in seconds.")
+
+
+#####################
+# MAIN TOOL & LOGIC #
+#####################
+class FirecrawlSearchTool(BaseTool[FirecrawlSearchToolInputSchema, FirecrawlSearchToolOutputSchema]):
+ """Tool for searching the web and news via the Firecrawl Search API."""
+
+ TIME_RANGES = {"day": "qdr:d", "week": "qdr:w", "month": "qdr:m", "year": "qdr:y"}
+
+ def __init__(self, config: FirecrawlSearchToolConfig = FirecrawlSearchToolConfig()):
+ super().__init__(config)
+ self.api_key = config.api_key or os.getenv("FIRECRAWL_API_KEY", "")
+ self.base_url = config.base_url.rstrip("/")
+ self.location = config.location
+ self.time_range = config.time_range
+ self.max_content_chars = config.max_content_chars
+ self.timeout = config.timeout
+
+ @classmethod
+ def _to_item(cls, hit: dict, query: str, max_content_chars: Optional[int] = None) -> FirecrawlSearchResultItem:
+ metadata = hit.get("metadata") if isinstance(hit.get("metadata"), dict) else {}
+ content = hit.get("markdown")
+ if content and max_content_chars:
+ content = content[:max_content_chars]
+ return FirecrawlSearchResultItem(
+ query=query,
+ title=hit.get("title") or metadata.get("title") or hit["url"],
+ url=hit["url"],
+ description=hit.get("description") or hit.get("snippet") or metadata.get("description"),
+ position=hit.get("position"),
+ published=hit.get("date"),
+ content=content,
+ )
+
+ def _build_body(self, query: str, params: FirecrawlSearchToolInputSchema) -> dict:
+ body = {
+ "query": query,
+ "limit": params.max_results_per_query,
+ "sources": [params.search_type],
+ "origin": "atomic-agents",
+ }
+ if self.location:
+ body["location"] = self.location
+ if self.time_range and params.search_type == "web":
+ body["tbs"] = self.TIME_RANGES[self.time_range]
+ if params.include_content:
+ body["scrapeOptions"] = {"formats": ["markdown"], "onlyMainContent": True}
+ return body
+
+ async def _fetch(
+ self,
+ session: aiohttp.ClientSession,
+ query: str,
+ params: FirecrawlSearchToolInputSchema,
+ ) -> List[FirecrawlSearchResultItem]:
+ async with session.post(f"{self.base_url}/search", json=self._build_body(query, params)) as resp:
+ try:
+ data = await resp.json(content_type=None)
+ except ValueError:
+ data = None
+ if resp.status != 200 or not isinstance(data, dict) or not data.get("success"):
+ error = data.get("error") if isinstance(data, dict) else None
+ raise Exception(f"Firecrawl search failed for '{query}': {resp.status} {error or resp.reason}")
+
+ # The key for the requested source is absent when there are no results.
+ groups = data.get("data") if isinstance(data.get("data"), dict) else {}
+ hits = groups.get(params.search_type) or []
+ items = [self._to_item(hit, query, self.max_content_chars) for hit in hits if isinstance(hit, dict) and hit.get("url")]
+ return items[: params.max_results_per_query]
+
+ async def run_async(self, params: FirecrawlSearchToolInputSchema) -> FirecrawlSearchToolOutputSchema:
+ if not self.api_key:
+ raise ValueError(
+ "Firecrawl API key is missing. Set FirecrawlSearchToolConfig.api_key or the FIRECRAWL_API_KEY "
+ "environment variable."
+ )
+
+ headers = {"Authorization": f"Bearer {self.api_key}", "Content-Type": "application/json"}
+ timeout = aiohttp.ClientTimeout(total=self.timeout)
+ async with aiohttp.ClientSession(headers=headers, timeout=timeout) as session:
+ tasks = [self._fetch(session, q, params) for q in params.queries]
+ grouped = await asyncio.gather(*tasks, return_exceptions=True)
+
+ # A bad key or exhausted credits fails every query; raise instead of returning an empty list.
+ failures = [group for group in grouped if isinstance(group, Exception)]
+ if failures and len(failures) == len(grouped):
+ raise failures[0]
+
+ results: List[FirecrawlSearchResultItem] = []
+ for query, group in zip(params.queries, grouped):
+ if isinstance(group, Exception):
+ logger.warning("Firecrawl query '%s' failed: %s", query, str(group) or repr(group))
+ continue
+ results.extend(group)
+ return FirecrawlSearchToolOutputSchema(results=results)
+
+ def run(self, params: FirecrawlSearchToolInputSchema) -> FirecrawlSearchToolOutputSchema:
+ with ThreadPoolExecutor() as executor:
+ return executor.submit(asyncio.run, self.run_async(params)).result()
+
+
+#################
+# EXAMPLE USAGE #
+#################
+if __name__ == "__main__": # pragma: no cover
+ from dotenv import load_dotenv
+ from rich.console import Console
+
+ load_dotenv()
+ console = Console()
+ tool = FirecrawlSearchTool(config=FirecrawlSearchToolConfig(api_key=os.getenv("FIRECRAWL_API_KEY", "")))
+
+ examples = [
+ ("web", False, "atomic agents framework"),
+ ("news", False, "AI agents"),
+ ("web", True, "atomic agents framework"),
+ ]
+ for search_type, include_content, query in examples:
+ output = tool.run(
+ FirecrawlSearchToolInputSchema(
+ queries=[query],
+ search_type=search_type,
+ max_results_per_query=3,
+ include_content=include_content,
+ )
+ )
+ console.rule(f"[bold cyan]{search_type}{' + content' if include_content else ''}")
+ for item in output.results:
+ console.print(f"[bold]{item.title}[/bold]")
+ console.print(item.url)
+ if item.description:
+ console.print(item.description[:200])
+ if item.published:
+ console.print(f"[bold]Published:[/bold] {item.published}")
+ if item.content:
+ console.print(f"[bold]Content:[/bold] {len(item.content)} chars")
+ console.print(item.content[:300])
+ console.print()
diff --git a/docs/guides/tools.md b/docs/guides/tools.md
index 5d29036..7d9e2a2 100644
--- a/docs/guides/tools.md
+++ b/docs/guides/tools.md
@@ -150,6 +150,7 @@ The Atomic Forge ships with several pre-built tools:
- **Calculator**: Perform mathematical calculations
- **DateTime**: Timezone-aware now / parse / convert / shift / diff (no key required)
- **Fía Signals**: Crypto market intelligence — market regime, trading signals, DeFi yields, gas prices, Solana trending tokens, and wallet risk scoring
+- **Firecrawl Search**: Web and news search via the Firecrawl API, with optional page content as Markdown
- **Hacker News Search**: Search HN stories, comments, Show HN, Ask HN, polls (free Algolia API)
- **PDF Reader**: Extract text and metadata from local or remote PDFs, with page-range filtering
- **SearXNG Search**: Search the web using SearXNG
diff --git a/uv.lock b/uv.lock
index 6c39d50..a357fa2 100644
--- a/uv.lock
+++ b/uv.lock
@@ -21,6 +21,7 @@ members = [
"example-mcp-server",
"fastapi-memory",
"fia-signals",
+ "firecrawl-search",
"hackernews-search",
"hooks-example",
"nested-multimodal",
@@ -1329,6 +1330,43 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/76/91/7216b27286936c16f5b4d0c530087e4a54eead683e6b0b73dd0c64844af6/filelock-3.20.0-py3-none-any.whl", hash = "sha256:339b4732ffda5cd79b13f4e2711a31b0365ce445d95d243bb996273d072546a2", size = 16054, upload-time = "2025-10-08T18:03:48.35Z" },
]
+[[package]]
+name = "firecrawl-search"
+version = "1.0.0"
+source = { editable = "atomic-forge/tools/firecrawl_search" }
+dependencies = [
+ { name = "aiohttp" },
+ { name = "atomic-agents" },
+ { name = "pydantic" },
+]
+
+[package.dev-dependencies]
+dev = [
+ { name = "coverage" },
+ { name = "pytest" },
+ { name = "pytest-asyncio" },
+ { name = "pytest-cov" },
+ { name = "python-dotenv" },
+ { name = "rich" },
+]
+
+[package.metadata]
+requires-dist = [
+ { name = "aiohttp", specifier = ">=3.9.0,<4.0.0" },
+ { name = "atomic-agents", editable = "." },
+ { name = "pydantic", specifier = ">=2.10.3,<3.0.0" },
+]
+
+[package.metadata.requires-dev]
+dev = [
+ { name = "coverage", specifier = ">=7.6.1,<8.0.0" },
+ { name = "pytest", specifier = ">=8.3.3,<9.0.0" },
+ { name = "pytest-asyncio", specifier = ">=0.23.5,<1.0.0" },
+ { name = "pytest-cov", specifier = ">=5.0.0,<6.0.0" },
+ { name = "python-dotenv", specifier = ">=1.0.0,<2.0.0" },
+ { name = "rich", specifier = ">=13.7.0,<14.0.0" },
+]
+
[[package]]
name = "flake8"
version = "7.3.0"