Metadata-Version: 2.5
Name: crewai-agentsearch
Version: 0.5.0
Summary: CrewAI tools for AgentSearch: free live web search, plus pay-per-call news, extract, JS render, screenshots and search-and-read (USDC on Base via x402, paid directly to AgentSearch)
Project-URL: Repository, https://github.com/agentsearchhq-coder/crewai-agentsearch
Project-URL: Issues, https://github.com/agentsearchhq-coder/crewai-agentsearch/issues
Project-URL: Homepage, https://agentsearchhq.com/?utm_source=crewai-agentsearch&utm_medium=package
Project-URL: Documentation, https://agentsearchhq.com/agents.md?utm_source=crewai-agentsearch&utm_medium=package
License-Expression: MIT
License-File: LICENSE
Keywords: agents,agentsearch,crewai,tools,web-search,x402
Requires-Python: >=3.10
Requires-Dist: crewai>=0.100
Requires-Dist: httpx>=0.25
Requires-Dist: pydantic>=2
Provides-Extra: paid
Requires-Dist: x402[evm]>=2.0; extra == 'paid'
Provides-Extra: test
Requires-Dist: pytest>=7; extra == 'test'
Description-Content-Type: text/markdown

# crewai-agentsearch

[CrewAI](https://www.crewai.com/) tools for [AgentSearch](https://agentsearchhq.com/?utm_source=crewai-agentsearch&utm_medium=package): live web search for agents. Free search needs no API key.

| Tool | Name | Cost |
|---|---|---|
| `AgentSearchTool` | `agentsearch_search` | **Free** (up to 25 searches/day per IP, up to 5 results, no key). Paid and unlimited only when you opt in (see Paid mode). |
| `AgentSearchNewsTool` | `agentsearch_news_search` | $0.008/call (recent news with publish dates; no results, no charge) |
| `AgentSearchExtractTool` | `agentsearch_extract` | $0.004/call (USDC on Base via x402 to AgentSearch) |
| `AgentSearchRenderTool` | `agentsearch_render` | $0.010/call (headless browser for JS pages) |
| `AgentSearchScreenshotTool` | `agentsearch_screenshot` | $0.010/call (PNG/JPEG saved to a local file; path returned) |
| `AgentSearchSearchAndReadTool` | `agentsearch_search_and_read` | $0.009/call (search plus the top pages' text in one payment) |

## Install

```bash
pip install -U crewai-agentsearch
```

## Quickstart

```python
from crewai import Agent, Crew, Task
from crewai_agentsearch import AgentSearchTool

search = AgentSearchTool()
print(search.run(query="latest CrewAI release", max_results=3))  # JSON string

researcher = Agent(role="Researcher", goal="Find current facts with sources",
                   backstory="You always cite URLs.", tools=[search])
task = Task(description="What changed in the latest CrewAI release?", expected_output="3 bullets with URLs", agent=researcher)
print(Crew(agents=[researcher], tasks=[task]).kickoff())
```

Add `AgentSearchNewsTool()`, `AgentSearchExtractTool()`, `AgentSearchRenderTool()`, `AgentSearchScreenshotTool()` and `AgentSearchSearchAndReadTool()` to `tools` once paid mode is set up.

### Filters, news and screenshots (0.5.0)

```python
from crewai_agentsearch import AgentSearchNewsTool, AgentSearchScreenshotTool, AgentSearchTool

AgentSearchTool(mode="paid").run(query="x402 payments", freshness="week", include_domains=["github.com"])
AgentSearchNewsTool().run(query="Base network USDC", freshness="day", country="us", max_results=8)
AgentSearchScreenshotTool().run(url="https://example.com", viewport={"width": 390, "height": 844})
# -> JSON with screenshot.path (image file) instead of base64, so the image never floods the model context
```

Paid search, news and search-and-read accept `freshness` (day/week/month/year), `date_from`/`date_to` (YYYY-MM-DD), `country`, `language`, and up to 5 `include_domains`/`exclude_domains`. Free search ignores filters. Extract accepts `max_chars` (up to 50000) and `include_links`. Screenshots are saved in `AGENTSEARCH_SCREENSHOT_DIR` (default: a temp folder).

## Paid mode

Install the `paid` extra (`pip install "crewai-agentsearch[paid]"`) and set `AGENTSEARCH_WALLET_PRIVATE_KEY` (or `POCKET_PRIVATE_KEY`) to the private key of a **new wallet made only for this**, funded with a little USDC on Base (e.g. $1; no ETH needed). Since 0.3.0 each call is paid over x402 **directly to AgentSearch's own API** (`https://api.agentsearchhq.com`, USDC on Base, settled only on success) using the official x402 Python SDK: search $0.008, news $0.008, extract $0.004, render $0.010, screenshot $0.010, search-and-read $0.009. $1 covers about 250 extracts or 111 search-and-read calls. Prefer the Pocket Network Agentic Portal ($0.005 per call)? Set `AGENTSEARCH_PAYMENT_ROUTE=pocket`.

News, extract, render, screenshot and search-and-read are always paid and need the key. News, screenshot and search-and-read exist only on the direct route (not on Pocket).

**Paid search is opt-in (changed in 0.2.1).** Setting a wallet key does *not* make search paid. `AgentSearchTool` (default `mode="auto"`) stays on free search until you opt in in one of two ways:

```python
AgentSearchTool(mode="paid")   # always paid search
```

```bash
export AGENTSEARCH_MODE=paid   # opt in for AgentSearchTool in the default mode="auto"
```

| Setup | `AgentSearchTool` search |
|---|---|
| `mode="auto"` (default), no `AGENTSEARCH_MODE` | Free, even if a wallet key is set |
| `mode="auto"` + `AGENTSEARCH_MODE=paid` | Paid |
| `mode="auto"` + paid opted in or a key set, but `[paid]` extra not installed | Free, with a logged warning |
| `mode="paid"` | Paid; without the `[paid]` extra it returns an error that tells you how to install it |
| `mode="free"` | Always free |

| Env var | Default |
|---|---|
| `AGENTSEARCH_MODE` | unset (`paid` opts `mode="auto"` in to paid search; `free` forces free) |
| `AGENTSEARCH_MAX_TOTAL_ATOMIC` | `1000000` ($1.00 per process) |
| `AGENTSEARCH_PAYMENT_ROUTE` | `direct` (AgentSearch's x402 API); `pocket` = Pocket Network Agentic Portal at $0.005/call |
| `AGENTSEARCH_MAX_PER_CALL_ATOMIC` | `20000` on the direct route, `5000` on Pocket ($0.020 / $0.005; can only be lowered) |
| `AGENTSEARCH_SCREENSHOT_DIR` | a temp folder (`agentsearch-screenshots`) |
| `AGENTSEARCH_TIMEOUT_MS` | `30000` |
| `AGENTSEARCH_EXTRACT_RENDER_FALLBACK` | unset (`1` turns on render fallback for extract, see below) |

Limits are checked before anything is signed. The key is never returned in tool output. Paid results include a `payment` object.

### Extract to render fallback

Set `AGENTSEARCH_EXTRACT_RENDER_FALLBACK=1` to make `AgentSearchExtractTool` automatically retry a URL with render when extract returns thin content (under 200 characters of text, typical for JavaScript-heavy pages). It is off by default because the render retry is a second paid call ($0.010, so up to $0.017 for that URL), still bounded by `AGENTSEARCH_MAX_TOTAL_ATOMIC`. You can also turn it on or off per call with the tool's `render_fallback` argument, which overrides the env var. When the fallback runs, the result includes a `render_fallback` object.

## Errors

Tools return `"Error: ..."` strings instead of raising. A 429 from the free relay means the free daily limit (up to 25 searches/day per IP) was hit, and the message explains how to upgrade.

See [CHANGELOG.md](CHANGELOG.md) for release notes.

## Development

```bash
pip install -e ".[test]" && pytest     # unit tests (mocked)
AGENTSEARCH_LIVE=1 pytest -k live       # one real free search
```

Docs: https://agentsearchhq.com/agents.md?utm_source=crewai-agentsearch&utm_medium=package

MIT
