Metadata-Version: 2.5
Name: crewai-agentsearch
Version: 0.6.2
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** with no wallet (25 free searches per IP in total, then pay per call, up to 5 results, no key). With a wallet and the `[paid]` extra, $0.003/call and unlimited (from 0.6.0; see Paid mode). |
| `AgentSearchNewsTool` | `agentsearch_news_search` | $0.003/call (recent news with publish dates; no results, no charge) |
| `AgentSearchExtractTool` | `agentsearch_extract` | $0.002/call (USDC on Base via x402 to AgentSearch) |
| `AgentSearchRenderTool` | `agentsearch_render` | $0.005/call (headless browser for JS pages) |
| `AgentSearchScreenshotTool` | `agentsearch_screenshot` | $0.004/call (PNG/JPEG saved to a local file; path returned) |
| `AgentSearchSearchAndReadTool` | `agentsearch_search_and_read` | $0.005/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.003, news $0.003, extract $0.002, render $0.005, screenshot $0.004, search-and-read $0.005. $1 covers about 500 extracts or 200 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).

**With a wallet, search is paid by default (changed in 0.6.0).** `AgentSearchTool` (default `mode="auto"`) pays $0.003 per search when a wallet is set and the `[paid]` extra is installed, and uses the free tier when no wallet is set. To keep search free with a wallet:

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

```bash
export AGENTSEARCH_MODE=free   # keep AgentSearchTool free in the default mode="auto"
```

| Setup | `AgentSearchTool` search |
|---|---|
| `mode="auto"` (default), no wallet | Free |
| `mode="auto"` (default) + wallet key or `AGENTSEARCH_WALLET_FILE` | Paid ($0.003) |
| `mode="auto"` + `AGENTSEARCH_MODE=free` | Free, even with a wallet |
| `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 |

Every search result has an `agentsearch_mode` field (`free: ...` / `paid: ...`), and the first paid search in a process logs one `AgentSearch search mode: paid ...` line. 0.2.1-0.5.x kept search free with a wallet unless you opted in.

**Reuse a wallet you already have (0.6.0+).** Instead of pasting a key, set `AGENTSEARCH_WALLET_FILE` to a file holding a 64-hex private key, or JSON with a `privateKey` field. `AGENTSEARCH_WALLET_FILE=agentcash` reuses AgentCash's `~/.agentcash/wallet.json`. The file is read only when signing and its contents are never logged. Encrypted keystores and remote signers (CDP server wallets) are not supported yet.

| Env var | Default |
|---|---|
| `AGENTSEARCH_MODE` | unset = `auto` (paid search when a wallet is set); `free` forces free; `paid` forces paid (in `mode="auto"`) |
| `AGENTSEARCH_WALLET_FILE` | unset (path to a wallet file instead of a pasted key; `agentcash` = `~/.agentcash/wallet.json`) |
| `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.005, so up to $0.007 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 search allowance (25 free searches per IP in total, then pay per call) is used up or shared daily capacity is reached, and the message explains how to upgrade. Search, news and search-and-read reject queries shorter than 2 characters (after trimming) before any request, so nothing is sent or charged; other 4xx errors from the free relay say to fix the input instead of retrying it unchanged.

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
