pydantic-ai-searxng 0.1.0

A SearXNG web-search tool for Pydantic AI agents.

pydantic-ai-searxng

A SearXNG web-search tool for Pydantic AI agents — modeled on the upstream duckduckgo and tavily common tools, but pointed at any SearXNG instance you control.

Why SearXNG?

SearXNG is a self-hostable metasearch engine that aggregates results from Google, DuckDuckGo, Bing, Wikipedia, GitHub, arXiv, and ~200 other sources. Pointing your agent at your own instance gives you:

• No third-party API keys, rate limits, or per-query billing.
• Full control over which engines, categories, and SafeSearch level the agent sees.
• Privacy: queries don't leave your infrastructure.

Deploy a SearXNG instance

Need an instance? One-click deploy on Railway:

Important: enable JSON on your SearXNG instance

JSON output is not enabled by default. You must add it to search.formats in settings.yml on the instance:

search:
  formats:
    - html
    - json

Without this, requests return HTML and this tool will raise a RuntimeError.

Install

pip install pydantic-ai-searxng
# or
uv add pydantic-ai-searxng

Usage

from pydantic_ai import Agent
from pydantic_ai_searxng import searxng_search_tool

agent = Agent(
    'openai:gpt-4o',
    tools=[searxng_search_tool('https://searxng.example.com')],
    system_prompt='Use the search tool to ground answers in current sources.',
)

result = agent.run_sync('What did Pydantic AI release this month?')
print(result.output)

Configuration

All keyword arguments are optional and are fixed at factory time (the LLM only sees query):

searxng_search_tool(
    'https://searxng.example.com',
    max_results=5,
    categories='general,news',
    engines='google,duckduckgo,wikipedia',
    language='en',
    safesearch=1,           # 0 off, 1 moderate, 2 strict
    time_range='week',      # day | week | month | year
    timeout=20.0,
)

Pass your own httpx.AsyncClient if you want shared connection pooling, custom headers, or a proxy:

import httpx

client = httpx.AsyncClient(headers={'User-Agent': 'my-agent/1.0'})
tool = searxng_search_tool('https://searxng.example.com', client=client)

Result shape

Each result is a TypedDict:

class SearxngResult(TypedDict):
    url: str
    title: str
    content: str
    engine: NotRequired[str]
    publishedDate: NotRequired[str]
    thumbnail: NotRequired[str]

Development

This project uses uv, ruff, and ty (Astral's type checker).

uv sync --extra dev
uv run ruff format .
uv run ruff check .
uv run ty check
uv run pytest
uv build

License

MIT