Skip to main content

crewai-agentsearch

CrewAI tools for AgentSearch: live web search for agents. Free search needs no API key.

Tool Name Cost
AgentSearchTool agentsearch_search Free with no wallet (up to 25 searches/day per IP, 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

pip install -U crewai-agentsearch

Quickstart

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)

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:

AgentSearchTool(mode="free")   # always free search
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 daily limit (up to 25 searches/day per IP) was hit, 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 for release notes.

Development

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

Metadata

Release files for crewai-agentsearch 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for crewai-agentsearch 0.6.0
File Size Uploaded Provenance Actions
crewai_agentsearch-0.6.0.tar.gz 23.8 kB Without provenance Details for crewai_agentsearch-0.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for crewai-agentsearch 0.6.0
File Interpreter ABI Platform Actions
crewai_agentsearch-0.6.0-py3-none-any.whl Python 3 none any Details for crewai_agentsearch-0.6.0-py3-none-any.whl

Total release size: 42.8 kB

Release files / crewai_agentsearch-0.6.0.tar.gz

Download URL crewai_agentsearch-0.6.0.tar.gz
Size 23.8 kB
Tags Source
SHA-256 checksum
How to use checksums
a33263c53e99d27c1726a98dd3c8e6e297caeaee4b2f44c68b9ea7a540b003fb
BLAKE2b-256 checksum
How to use checksums
d32c650d8a6d8c20cc2ead10d18c37255d773269cc5e20e393bc58d8bb5775a6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.14

Release files / crewai_agentsearch-0.6.0-py3-none-any.whl

Download URL crewai_agentsearch-0.6.0-py3-none-any.whl
Size 19.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0c1ee042b04b872198fa9ba1be61860512c37462408689d6520ccf1db01bee88
BLAKE2b-256 checksum
How to use checksums
9912d77f988dcd9f3adf33e7d3862aa714811918cbdcc995e46e1a678c19dd30
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.14

Security for crewai-agentsearch 0.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page