Integration: Serpex

Multi-engine web search for Haystack — access Google, Bing, DuckDuckGo, Brave, Yahoo, and Yandex via Serpex API

Authors

Divyesh Radadiya

Table of Contents

• Overview
• Installation
• Usage
• License

Overview

Serpex is a unified web search API that provides access to multiple search engines through a single interface. This Haystack integration allows you to seamlessly incorporate web search results into your Haystack RAG (Retrieval-Augmented Generation) pipelines and AI applications.

Website: serpex.dev

Key Features

• 🔍 Multi-Engine Support: Switch between Google, Bing, DuckDuckGo, Brave, Yahoo, and Yandex
• ⚡ High Performance: Fast and reliable API with automatic retries
• 🎯 Rich Results: Get organic search results with titles, snippets, and URLs
• 🕒 Time Filters: Filter results by day, week, month, or year
• 🔒 Type-Safe: Fully typed with comprehensive type hints
• 📝 Haystack Native: Seamless integration with Haystack 2.0+ components

Installation

pip install serpex-haystack

Usage

Basic Usage

from haystack.utils import Secret
from haystack_integrations.components.websearch.serpex import SerpexWebSearch

# Initialize the component
web_search = SerpexWebSearch(
    api_key=Secret.from_env_var("SERPEX_API_KEY"),
    engine="google",  # Options: google, bing, duckduckgo, brave, yahoo, yandex
)

# Perform a search
results = web_search.run(query="What is Haystack AI?")

# Access the results
for doc in results["documents"]:
    print(f"Title: {doc.meta['title']}")
    print(f"URL: {doc.meta['url']}")
    print(f"Snippet: {doc.content}\n")

Agent Example

Use Serpex in a Haystack agent for dynamic web search:

import os
from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.dataclasses import ChatMessage
from haystack.tools import ComponentTool
from haystack.utils import Secret
from haystack_integrations.components.websearch.serpex import SerpexWebSearch

os.environ["OPENAI_API_KEY"] = "<YOUR OPENAI API KEY>"

# Create a web search tool
search_tool = ComponentTool(component=SerpexWebSearch(api_key=Secret.from_env_var("SERPEX_API_KEY")))

# Create an agent with web search capability
basic_agent = Agent(
    chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"),
    system_prompt="You are a helpful web agent.",
    tools=[search_tool],
)

# Ask the agent a question that requires web search
result = basic_agent.run(messages=[ChatMessage.from_user("What are the latest developments in AI agents?")])

print(result['last_message'].text)

Advanced Features

Multiple Search Engines

# Compare results from different engines
google_search = SerpexWebSearch(engine="google")
bing_search = SerpexWebSearch(engine="bing")
duckduckgo_search = SerpexWebSearch(engine="duckduckgo")

Time Range Filtering

# Get only recent results
recent_results = web_search.run(
    query="AI news",
    time_range="week"  # Options: "day", "week", "month", "year", "all"
)

Runtime Configuration Override

# Override default settings per query
results = web_search.run(
    query="Python tutorials",
    engine="duckduckgo",  # Override default engine
)

Component API

SerpexWebSearch

Parameters:

• api_key (Secret): Serpex API key. Defaults to SERPEX_API_KEY environment variable.
• engine (str): Search engine to use. Options: "auto", "google", "bing", "duckduckgo", "brave", "yahoo", "yandex". Default: "google".
• timeout (float): Request timeout in seconds. Default: 10.0.
• retry_attempts (int): Number of retry attempts. Default: 2.

Inputs:

• query (str): The search query string.
• engine (str, optional): Override the default search engine.
• time_range (str, optional): Filter by time range ("all", "day", "week", "month", "year").

Outputs:

• documents (List[Document]): List of Haystack Document objects containing search results.

Each document includes:

• content: The search result snippet
• meta:
  • title: Result title
  • url: Result URL
  • position: Position in search results
  • query: Original search query
  • engine: Search engine used

License

serpex-haystack is distributed under the terms of the Apache-2.0 license.