From cbf4c1c6e464bfe066eb0474bef151fb60cd5def Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Fri, 17 Jul 2026 09:50:28 +0000
Subject: [PATCH] docs: add ScrapeGraphAI tool reference for v2 SDK migration
---
agentor/api/tools/scrapegraphai.mdx | 213 ++++++++++++++++++++++++++++
agentor/installation.mdx | 4 +
docs.json | 1 +
3 files changed, 218 insertions(+)
create mode 100644 agentor/api/tools/scrapegraphai.mdx
diff --git a/agentor/api/tools/scrapegraphai.mdx b/agentor/api/tools/scrapegraphai.mdx
new file mode 100644
index 0000000..2b432cd
--- /dev/null
+++ b/agentor/api/tools/scrapegraphai.mdx
@@ -0,0 +1,213 @@
+---
+title: "ScrapeGraphAI"
+description: "ScrapeGraphAI tool reference: agents scrape pages, extract structured data, run web searches, crawl sites, and schedule change monitors via the scrapegraph-py 2.x SDK."
+---
+
+`ScrapeGraphAI` gives an agent a full web-data toolkit backed by the [ScrapeGraphAI](https://scrapegraphai.com) API: fetch pages in different formats, pull structured data with an AI prompt, search the web, run multi-page crawls, and schedule change monitors.
+
+Use it when your agent needs live web content or LLM-ready extractions without you writing a scraper, browser automation, or search wrapper.
+
+## Installation
+
+
+ The `scrapegraph` extra pulls in `scrapegraph-py>=2.1.0`, which requires **Python 3.12 or newer**. On Python 3.10 or 3.11, `pip install agentor[scrapegraph]` succeeds but the SDK is not installed, and instantiating `ScrapeGraphAI` raises `ImportError`.
+
+
+```bash theme={null}
+pip install "agentor[scrapegraph]"
+```
+
+## Authentication
+
+Set your ScrapeGraphAI API key as an environment variable:
+
+```bash theme={null}
+export SGAI_API_KEY=your_scrapegraph_key
+```
+
+The constructor resolves the key in this order:
+
+1. The `api_key` argument, if passed.
+2. The `SGAI_API_KEY` environment variable (the new SDK default).
+3. The `SCRAPEGRAPH_API_KEY` environment variable (legacy fallback for pre-2.x deployments).
+
+## Constructor
+
+
+ ScrapeGraphAI API key. Falls back to `SGAI_API_KEY`, then to `SCRAPEGRAPH_API_KEY`.
+
+
+## Capabilities
+
+Every capability returns a JSON string on success or an `Error in : ...` string on failure — so results are always agent-consumable.
+
+### scrape
+
+Fetch a webpage and return its content.
+
+
+ The URL to scrape.
+
+
+
+ Output format: `"markdown"`, `"html"`, `"links"`, or `"summary"`.
+
+
+### extract
+
+Extract structured data from a URL using an AI prompt.
+
+
+ What to extract, e.g. `"Extract product names and prices"`.
+
+
+
+ The page to extract from.
+
+
+
+ Optional JSON schema describing the desired output shape.
+
+
+### search
+
+Search the web and optionally AI-extract from the results.
+
+
+ Search query.
+
+
+
+ Number of results to return (1–20).
+
+
+
+ Optional extraction prompt applied to the results.
+
+
+### crawl
+
+Start a crawl job. Returns the crawl id and initial status — poll it with `get_crawl_result`.
+
+
+ Seed URL.
+
+
+
+ Maximum pages to crawl.
+
+
+
+ Maximum link depth from the seed.
+
+
+
+ Optional path globs to include (e.g. `["/blog/*"]`).
+
+
+
+ Optional path globs to exclude (e.g. `["/admin/*"]`).
+
+
+### get\_crawl\_result
+
+Fetch the status and results of a crawl.
+
+
+ Crawl id returned by `crawl`.
+
+
+### stop\_crawl / resume\_crawl / delete\_crawl
+
+Manage a crawl job's lifecycle by id. Each takes a single `crawl_id: str` argument.
+
+### monitor
+
+Create a scheduled monitor that re-scrapes a page on a cron schedule.
+
+
+ Page to monitor.
+
+
+
+ Cron expression, e.g. `"0 * * * *"` for hourly.
+
+
+
+ Optional monitor name.
+
+
+
+ Optional webhook to receive change notifications.
+
+
+### list\_monitors / get\_monitor / pause\_monitor / resume\_monitor / delete\_monitor
+
+Manage scheduled monitors. `list_monitors` takes no arguments; the others take a single `monitor_id: str`.
+
+### credits
+
+Return plan info and remaining API credits.
+
+### health
+
+Return API health status.
+
+## Usage
+
+### With an Agentor agent
+
+```python theme={null}
+import os
+
+from agentor import Agentor
+from agentor.tools import ScrapeGraphAI
+
+agent = Agentor(
+ name="ScrapeGraph Agent",
+ model="gpt-5-mini",
+ tools=[ScrapeGraphAI(api_key=os.environ["SGAI_API_KEY"])],
+ instructions="Use ScrapeGraphAI tools for extraction from websites.",
+)
+
+result = agent.run(
+ "Extract https://celesto.ai/blog and write a short summary in markdown."
+)
+print(result.final_output)
+```
+
+### Direct capability calls
+
+```python theme={null}
+from agentor.tools import ScrapeGraphAI
+
+scraper = ScrapeGraphAI() # reads SGAI_API_KEY from the environment
+
+# Fetch a page as markdown
+print(scraper.scrape("https://celesto.ai", format="markdown"))
+
+# Pull structured data
+print(scraper.extract(
+ prompt="Extract the title and author of each blog post",
+ url="https://celesto.ai/blog",
+))
+
+# Kick off a crawl and poll it
+job = scraper.crawl("https://celesto.ai", max_pages=25, max_depth=3)
+# job is a JSON string containing an `id` you pass to get_crawl_result
+```
+
+## Error handling
+
+Capabilities never raise for API-level failures — the tool converts SDK errors into a string an LLM can act on:
+
+```python theme={null}
+scraper.scrape("https://not-a-real-domain.example")
+# → 'Error in scrape: '
+```
+
+If `scrapegraph-py` isn't installed, or if you're on Python 3.10 / 3.11 where the 2.x SDK cannot be installed, the constructor raises `ImportError` with an explanation.
+
+## Source reference
+
+`src/agentor/tools/scrapegraphai.py`
diff --git a/agentor/installation.mdx b/agentor/installation.mdx
index 28f551f..2fb6163 100644
--- a/agentor/installation.mdx
+++ b/agentor/installation.mdx
@@ -83,6 +83,10 @@ pip install agentor[slack]
pip install agentor[scrapegraph]
```
+
+ The `scrapegraph` extra requires **Python 3.12 or newer** because `scrapegraph-py>=2.1.0` does not ship wheels for Python 3.10 or 3.11. On older interpreters, the extra installs but the SDK is skipped, and instantiating `ScrapeGraphAI` raises `ImportError`. See the [ScrapeGraphAI tool reference](/agentor/api/tools/scrapegraphai) for the full capability surface.
+
+
### Install all optional dependencies
```bash theme={null}
diff --git a/docs.json b/docs.json
index 959755f..be9aff4 100644
--- a/docs.json
+++ b/docs.json
@@ -290,6 +290,7 @@
"agentor/api/tools/github",
"agentor/api/tools/git",
"agentor/api/tools/gmail",
+ "agentor/api/tools/scrapegraphai",
"agentor/api/tools/shell",
"agentor/api/tools/weather",
"agentor/api/tools/web-search",