WebSearchTool API Reference

The WebSearchTool allows agents to perform web searches using one or more SearxNG instances. SearxNG is a privacy-respecting, open-source metasearch engine.

Overview

This tool queries a configured SearxNG instance to find web pages relevant to a given search query. It returns a list of search results, including titles, snippets, and links.

To use this tool effectively, agents can first use WebSearchTool to find relevant URLs and then use the WebPageContentTool to fetch the actual content of specific pages.

Setup

1. Find or Host a SearxNG Instance: You need access to a SearxNG instance. You can find public instances at searx.space or host your own.
2. Configure Environment Variable: Set the SEARX_INSTANCE_URL environment variable in your project (e.g., in a .env file) to the URL of your chosen SearxNG instance(s).
   • Single instance: SEARX_INSTANCE_URL=https://searx.example.com
   • Multiple instances (comma-separated): SEARX_INSTANCE_URL=https://searx.example.com,https://another.searx.instance.org

If SEARX_INSTANCE_URL is not set or no valid URLs are provided, the tool will log a warning and searches will fail.

WebSearchTool Class

This class extends Tool.

Constructor

constructor()

Creates a new WebSearchTool instance. The constructor reads the SEARX_INSTANCE_URL environment variable to configure the SearxNG instance(s) it will use.

• Tool Name: "WebSearch"
• Tool Description: "Search the web for information using Searx"
• Tool Parameters:
  • query: string (required): The search query.
  • numResults: number (optional, default: 5): The desired number of search results to return.
• Tool ReturnType Description: "Returns search results with titles, snippets, and links. Links should be used to get the content of the page using the web page content tool."

run Method

The core logic is implemented in the protected async run() method, which is invoked by the execute() method of the base Tool class.

protected async run(params: { query: string; numResults?: number }): Promise<WebSearchResults>

• params: { query: string; numResults?: number }: An object containing:
  • query: string: The search query.
  • numResults?: number: The number of results to aim for (defaults to 5 if not provided).
• Returns: A Promise that resolves to a WebSearchResults object.

WebSearchResults Object Structure (Conceptual)

The object returned by the run method typically has the following structure:

interface WebSearchResultItem {
  title: string;       // Title of the search result
  link: string;        // URL of the search result
  snippet?: string;    // A short description or snippet from the page
  // engine?: string;   // Search engine that provided this result (if available from SearxNG)
  // category?: string; // Category of the result (e.g., general, images, news)
}

interface WebSearchResults {
  query: string;                      // The original search query
  totalResults?: number;             // Estimated total number of results found by SearxNG (may not always be accurate or present)
  results: WebSearchResultItem[];     // Array of search result items
  error?: string;                    // Error message if the search failed
  errorDetails?: string;             // More details about the error
  warning?: string;                  // Warning message (e.g., if falling back to cached results)
}

Note: The actual fields within WebSearchResultItem and WebSearchResults might vary slightly based on the SearxNG instance and the data it provides.

Example Usage with an Agent

// Conceptual example of how an Agent might use WebSearchTool
import { Agent, AgentForge, LLM, WebSearchTool } from "agent-forge";
import dotenv from 'dotenv';

dotenv.config(); // Ensure SEARX_INSTANCE_URL is loaded

async function searchWithAgent() {
  const apiKey = process.env.OPENAI_API_KEY;
  if (!apiKey) { return; }

  const llmProvider = new LLM("openai", { apiKey });
  const forge = new AgentForge(llmProvider);

  const searchTool = new WebSearchTool();
  forge.registerTool(searchTool);

  const searchAgentConfig = {
    name: "ResearcherAgent",
    role: "Web Researcher",
    description: "An agent that uses web search to find information.",
    objective: "Find relevant web pages for a given query.",
    model: "gpt-4-turbo",
    tools: [searchTool.getConfig()], // Provide tool configuration
  };
  const searchAgent = new Agent(searchAgentConfig, [searchTool], llmProvider);
  forge.registerAgent(searchAgent);

  try {
    const result = await searchAgent.run("What are the latest developments in AI assistants?");
    // The agent's LLM would have decided to use WebSearch and formulated the params.
    // The result.output here would be the LLM's response after processing search results.
    console.log("Agent Output based on search:", result.output);

    // To see the direct tool call details made by the agent:
    if (result.metadata?.toolCalls && result.metadata.toolCalls.length > 0) {
      result.metadata.toolCalls.forEach(call => {
        if (call.toolName === "WebSearch") {
          console.log("WebSearch Tool Call Parameters:", call.parameters);
          console.log("WebSearch Tool Call Result (snippet):", JSON.stringify(call.result, null, 2).substring(0, 500) + "...");
        }
      });
    }

  } catch (error) {
    console.error("Error running search agent:", error);
  }
}

// searchWithAgent();

This tool relies on external SearxNG instances and includes features like instance health checking, round-robin selection, caching, and rate limiting to ensure reliable operation and respect for public instance resources.