AgentSearch Tool Spec (llama-index-tools-agentsearch)

A LlamaIndex ToolSpec for AgentSearch: live web search for agents. Free search needs no API key.

Install

pip install -U llama-index-tools-agentsearch

Quickstart

from llama_index.tools.agentsearch import AgentSearchToolSpec

spec = AgentSearchToolSpec()
print(spec.search("latest LlamaIndex release", max_results=3))  # JSON string

# With an agent
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI

agent = FunctionAgent(tools=spec.to_tool_list(), llm=OpenAI(model="gpt-4o-mini"))
# response = await agent.run("What changed in the latest LlamaIndex release? Cite URLs.")

Free-only tool list: [t for t in spec.to_tool_list() if t.metadata.name == "search"]. Force free search even with a wallet set: AgentSearchToolSpec(mode="free").

Paid mode

Install the paid extra (pip install "llama-index-tools-agentsearch[paid]") and set AGENTSEARCH_WALLET_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). Each call costs $0.005 and is paid over x402 through the Pocket Network Agentic Portal using the official x402 Python SDK. With a key set, search also goes paid and unlimited.

Limits are checked before anything is signed. The key is never logged or returned. Paid results include a payment object.

Errors

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

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=llama-index-tools-agentsearch&utm_medium=package

MIT