Skip to main content
from praisonaiagents import Agent, search_web

agent = Agent(
    name="Private Search",
    instructions="Search the web via the local SearxNG instance.",
    tools=[search_web],
)
agent.start("Search for privacy-focused search engines and summarise")
The user asks for web results; the agent queries SearxNG instead of a commercial search API.

​
SearxNG Search Tool

The SearxNG search tool allows you to perform web searches using your local SearxNG instance, providing privacy-focused search capabilities as an alternative to traditional search engines like Google or DuckDuckGo.

​
Quick Start

1

Start SearxNG with Docker

docker run -d -p 8080:8080 searxng/searxng
2

Search with agent

from praisonaiagents import Agent, search_web

agent = Agent(
    name="PrivateSearchAgent",
    instructions="Search the web privately using SearxNG.",
    tools=[search_web],
)

agent.start("Search for Python tutorials")

​
Overview

SearxNG is a privacy-respecting metasearch engine that aggregates results from multiple search engines without storing your data. This tool integrates with your local SearxNG instance to provide secure, private web searches for your AI agents.

​
Installation

First, install the required dependency: 
pip install requests
You’ll also need a running SearxNG instance. You can set it up using Docker: 
# Run SearxNG locally on port 32768
docker run -d --name searxng -p 32768:8080 searxng/searxng

​
Usage

​
Basic Usage

from praisonaiagents import searxng_search

# Basic search
results = searxng_search("AI news")

# With custom parameters
results = searxng_search(
    query="Python programming", 
    max_results=10,
    searxng_url="http://localhost:32768/search"
)

# Display results
for result in results:
    print(f"Title: {result['title']}")
    print(f"URL: {result['url']}")
    print(f"Snippet: {result['snippet']}")
    print("-" * 50)

​
Using the Alias

from praisonaiagents import searxng

# Same functionality as searxng_search
results = searxng("machine learning tutorials")

​
Integration with Agents

from praisonaiagents import Agent, Task
from praisonaiagents import searxng_search

# Create an agent with SearxNG search capability
search_agent = Agent(
    name="Search Agent",
    instructions="You are a search assistant that helps users find information using SearxNG.",
    tools=[searxng_search]
)

# Create a task
task = Task(
    description="Search for the latest developments in artificial intelligence",
    agent=search_agent
)

# Execute the task
result = agent.start(task.description)
print(result)

​
Function Parameters

​
searxng_search(query, max_results=5, searxng_url=None)

Parameters:
  • query (str, required): The search query string
  • max_results (int, optional): Maximum number of results to return. Default: 5
  • searxng_url (str, optional): URL of your SearxNG instance. Default: “http://localhost:32768/search”
Returns:
  • List[Dict]: List of search results, each containing:
    • title: The title of the search result
    • url: The URL of the search result
    • snippet: A brief snippet/description of the content
    • error: Error message if the search fails

​
Configuration

​
Environment Variables

You can configure SearxNG behavior using environment variables: 
import os

# Set default SearxNG URL
os.environ['SEARXNG_URL'] = 'http://my-searxng-server:8080/search'

# Connection timeout (in seconds)
os.environ['SEARXNG_TIMEOUT'] = '10'

# Maximum results per search
os.environ['SEARXNG_MAX_RESULTS'] = '20'

# Enable/disable SSL verification
os.environ['SEARXNG_VERIFY_SSL'] = 'true'

# The tool will use these defaults if none are provided
results = searxng_search("AI research")

​
SearxNG Instance Configuration

Configure your SearxNG instance by editing the settings.yml file: 
# /etc/searxng/settings.yml
use_default_settings: true

server:
  port: 8080
  bind_address: "0.0.0.0"
  secret_key: "your-secret-key-here"
  limiter: true  # Enable rate limiting
  
search:
  safe_search: 0  # 0: None, 1: Moderate, 2: Strict
  autocomplete: "duckduckgo"
  default_lang: "en"
  max_ban_time_on_fail: 120  # seconds
  
engines:
  - name: google
    engine: google
    shortcut: g
    disabled: false
  - name: duckduckgo
    engine: duckduckgo
    shortcut: ddg
    disabled: false
  - name: wikipedia
    engine: wikipedia
    shortcut: wiki
    disabled: false
    
outgoing:
  request_timeout: 6.0  # seconds
  max_request_timeout: 10.0  # seconds
  useragent_suffix: "PraisonAI"
  pool_connections: 100
  pool_maxsize: 10

​
Advanced Configuration Options

​
Rate Limiting Configuration

# Configure rate limiting for your SearxNG tool
from praisonaiagents import searxng_search
import time

class RateLimitedSearxNG:
    def __init__(self, max_requests_per_minute=30):
        self.max_requests = max_requests_per_minute
        self.requests = []
        
    def search(self, query, **kwargs):
        # Check rate limit
        now = time.time()
        self.requests = [r for r in self.requests if now - r < 60]
        
        if len(self.requests) >= self.max_requests:
            wait_time = 60 - (now - self.requests[0])
            time.sleep(wait_time)
            
        self.requests.append(now)
        return searxng_search(query, **kwargs)

# Use rate-limited search
rate_limited_search = RateLimitedSearxNG(max_requests_per_minute=30)
results = rate_limited_search.search("AI news")

​
Authentication Configuration

# If your SearxNG instance requires authentication
import requests
from functools import partial

def authenticated_searxng_search(query, auth_token, **kwargs):
    headers = {"Authorization": f"Bearer {auth_token}"}
    searxng_url = kwargs.get('searxng_url', 'http://localhost:32768/search')
    
    # Add authentication headers
    response = requests.get(
        searxng_url,
        params={'q': query, 'format': 'json'},
        headers=headers,
        timeout=10
    )
    
    # Process response...
    return response.json()

# Create authenticated search tool
auth_token = "your-auth-token"
secure_search = partial(authenticated_searxng_search, auth_token=auth_token)

​
Proxy Configuration

# Configure SearxNG to use proxies
proxies = {
    'http': 'http://proxy.example.com:8080',
    'https': 'https://proxy.example.com:8080'
}

# Custom search with proxy
def proxied_searxng_search(query, **kwargs):
    import requests
    
    searxng_url = kwargs.get('searxng_url', 'http://localhost:32768/search')
    response = requests.get(
        searxng_url,
        params={'q': query, 'format': 'json'},
        proxies=proxies,
        timeout=10
    )
    return response.json()

​
Search Categories and Filtering

Configure search categories and filters: 
# Search specific categories
params = {
    'q': 'machine learning',
    'categories': 'science,it',  # Comma-separated categories
    'engines': 'google,duckduckgo',  # Specific engines
    'lang': 'en',  # Language preference
    'time_range': 'month',  # day, week, month, year
    'safesearch': 1  # 0: off, 1: moderate, 2: strict
}

# Custom search with filters
def filtered_searxng_search(query, categories=None, time_range=None, **kwargs):
    import requests
    
    searxng_url = kwargs.get('searxng_url', 'http://localhost:32768/search')
    
    params = {'q': query, 'format': 'json'}
    if categories:
        params['categories'] = categories
    if time_range:
        params['time_range'] = time_range
        
    # Make request with custom parameters
    try:
        response = requests.get(searxng_url, params=params, timeout=10)
        response.raise_for_status()
        data = response.json()
        
        # Extract and format results
        results = []
        for result in data.get('results', []):
            results.append({
                'title': result.get('title', ''),
                'url': result.get('url', ''),
                'snippet': result.get('content', '')
            })
        return results
    except Exception as e:
        return [{'error': f'Search failed: {str(e)}'}]
    
# Usage
recent_ai_news = filtered_searxng_search(
    "artificial intelligence",
    categories="news",
    time_range="week"
)

​
SearxNG Setup

For production use, consider:
  1. Custom SearxNG Configuration: Configure engines, categories, and settings
  2. Authentication: Set up authentication if needed
  3. Rate Limiting: Configure appropriate rate limits
  4. SSL/TLS: Use HTTPS for secure connections
  5. Monitoring: Set up logging and monitoring
  6. Caching: Configure Redis for result caching
  7. Load Balancing: Use multiple SearxNG instances

​
Advanced Usage

​
Multi-Agent Search System

from praisonaiagents import Agent, Task, Process
from praisonaiagents import searxng_search

# Research agent
researcher = Agent(
    name="Researcher",
    instructions="Search for academic and technical information",
    tools=[searxng_search]
)

# News agent
news_agent = Agent(
    name="News Agent", 
    instructions="Search for latest news and current events",
    tools=[searxng_search]
)

# Tasks
research_task = Task(
    description="Find recent research papers on quantum computing",
    agent=researcher
)

news_task = Task(
    description="Find latest news about AI developments",
    agent=news_agent
)

# Process
process = Process(
    agents=[researcher, news_agent],
    tasks=[research_task, news_task]
)

result = process.run()

​
Custom SearxNG Configuration

from praisonaiagents import searxng_search

# Search with specific SearxNG instance
results = searxng_search(
    query="sustainable energy",
    max_results=15,
    searxng_url="https://my-private-searxng.com/search"
)

​
Error Handling

The tool includes comprehensive error handling: 
results = searxng_search("test query")

for result in results:
    if "error" in result:
        print(f"Search error: {result['error']}")
    else:
        print(f"Found: {result['title']}")

​
Common Error Messages

  • Connection Error: “Could not connect to SearxNG at . Ensure SearxNG is running.”
  • Timeout Error: “SearxNG search request timed out”
  • Missing Dependency: “SearxNG search requires requests package. Install with: pip install requests”
  • Parsing Error: “Error parsing SearxNG response: “

​
Best Practices

Use a local SearxNG instance for better privacy and performance
Be mindful of search frequency to avoid overwhelming your instance
Always check for errors in the response
Use environment variables for different deployment environments
Validate search results before using them in your application

​
Comparison with Other Search Tools

FeatureSearxNGDuckDuckGoGoogle
Privacy✅ High⚡ Medium❌ Low
Local Control✅ Yes❌ No❌ No
Multi-Engine✅ Yes❌ No❌ No
Customization✅ High❌ Limited❌ None

​
Troubleshooting

​
SearxNG Not Responding

# Check if SearxNG is running
curl http://localhost:32768/search?q=test&format=json

# Restart SearxNG container
docker restart searxng

​
Connection Issues

# Test connection before using
import requests

try:
    response = requests.get("http://localhost:32768/search", timeout=5)
    print("SearxNG is accessible")
except requests.exceptions.ConnectionError:
    print("Cannot connect to SearxNG")
For more information about SearxNG setup and configuration, visit the official SearxNG documentation.

Custom Tools

Build your own agent tools

Tools Overview

Browse PraisonAI tool documentation