Add Firecrawl Search tool to the Atomic Forge

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

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

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)

atomic-forge/tools/firecrawl_search/.coveragerc

@@ -0,0 +1,8 @@
+[run]
+source = tool
+omit = */tests/*
+
+[report]
+exclude_lines =
+    if __name__ == "__main__":
+show_missing = True

atomic-forge/tools/firecrawl_search/README.md

@@ -0,0 +1,62 @@
+# 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` (`SecretStr`, a plain string is accepted): Firecrawl API key. Falls back to the `FIRECRAWL_API_KEY` environment variable when empty. It is only sent in the `Authorization` header. Raised errors, log messages and `failures` redact the configured key (when it is at least 8 characters) and anything in Firecrawl's `fc-` 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 (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], at least one): search queries to run. Duplicates are sent once. 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
+- `results`: 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). 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's `idna` codec produces it) are skipped, and badly typed optional fields are left empty.
+- `failures`: queries that failed while others returned results, each with `query` and `error` (the HTTP status and the API's error message). Keys are redacted from both as described for `api_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.
+
+```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.

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 = "juan@sideguide.dev" }
+]
+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 }

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