feat(agent-tars): add searxng search (close: #326) (#372)

Author: le0zh

apps/agent-tars/docs/images/search-searxng.png

@@ -0,0 +1,47 @@
+# SearXNG Search Configuration
+
+## Overview
+
+SearXNG is a privacy-respecting, self-hosted metasearch engine that aggregates results from various search engines. This document explains how to configure SearXNG search in Agent TARS.
+
+## How to Use
+
+[search-searxng](../images/search-searxng.png)
+
+## Configuration Options
+
+### Basic Configuration
+
+To use SearXNG search, you need to specify the following parameters:
+
+| Parameter | Description | Default Value |
+|-----------|-------------|---------------|
+| `baseUrl` | URL of the SearXNG instance | `https://127.0.0.1:8081` |
+
+### Advanced Options
+
+> The following configurations are optional and currently use default values. In the future, configuration via the GUI will be supported.
+
+When performing searches, you can customize the following options:
+
+| Option | Description | Default Value |
+|--------|-------------|---------------|
+| `count` | Maximum number of results to return | 10 |
+| `language` | Search language code | `zh-CN` |
+| `categories` | Categories to search in (e.g., general, images, news) | `['general']` |
+| `time_range` | Time range for results (e.g., day, week, month, year) | - |
+| `safesearch` | Safe search level (0: off, 1: moderate, 2: strict) | 1 |
+
+## Setting Up SearXNG
+
+### Using a Public Instance
+
+You can use a public SearXNG instance by setting the `baseUrl` to the instance URL. However, for privacy and reliability reasons, we recommend hosting your own instance.
+
+### Self-Hosting SearXNG
+
+To set up your own SearXNG instance:
+
+1. Follow the [official SearXNG installation guide](https://searxng.github.io/searxng/admin/installation.html)
+2. Configure your instance according to your needs
+3. Update the `baseUrl` in Agent TARS settings to point to your instance

apps/agent-tars/docs/settings/search-searxng.md

@@ -89,6 +89,18 @@ export async function search(toolCall: ToolCall): Promise<MCPToolResult> {
       //     query: args.query,
       //     count: args.count || 10,
       //   });
+    } else if (currentSearchConfig.provider === SearchProvider.SEARXNG) {
+      const client = new SearchClient({
+        provider: SearchProviderEnum.SearXNG,
+        providerConfig: {
+          baseUrl: currentSearchConfig.baseUrl,
+        },
+      });
+
+      results = await client.search({
+        query: args.query,
+        count: args.count,
+      });
     } else {
       // Only for Bing Search, because Tavily is not supported in the bundle of this packages
       // Error info: trvily is not defined

apps/agent-tars/src/main/customTools/search.ts

@@ -48,6 +48,12 @@ export function SearchSettingsTab({
         >
           Bing Search
         </SelectItem>
+        <SelectItem
+          key={SearchProvider.SEARXNG}
+          startContent={getSearchProviderLogo(SearchProvider.SEARXNG)}
+        >
+          SearXNG Search
+        </SelectItem>
       </Select>
 
       {[SearchProvider.TAVILY, SearchProvider.BING_SEARCH].includes(
@@ -100,6 +106,18 @@ export function SearchSettingsTab({
           description="Override the default Bing Search API endpoint"
         />
       )}
+
+      {settings.provider === SearchProvider.SEARXNG && (
+        <Input
+          label="Custom Endpoint"
+          placeholder="https://127.0.0.1:8081/"
+          value={settings.baseUrl || ''}
+          onChange={(e) =>
+            setSettings({ ...settings, baseUrl: e.target.value })
+          }
+          description="Override the default SearXNG API endpoint"
+        />
+      )}
     </div>
   );
 }

apps/agent-tars/src/renderer/src/components/LeftSidebar/Settings/SearchSettingsTab.tsx

@@ -1,4 +1,4 @@
-import { SiDuckduckgo, SiMicrosoftbing } from 'react-icons/si';
+import { SiDuckduckgo, SiMicrosoftbing, SiSearxng } from 'react-icons/si';
 import { TbSearch } from 'react-icons/tb';
 import { SearchProvider } from '@agent-infra/shared';
 
@@ -10,6 +10,8 @@ export function getSearchProviderLogo(provider: SearchProvider) {
       return <TbSearch size={18} />;
     case SearchProvider.DUCKDUCKGO_SEARCH:
       return <SiDuckduckgo size={18} />;
+    case SearchProvider.SEARXNG:
+      return <SiSearxng size={18} />;
     // case SearchProvider.BROWSER_SEARCH:
     //   return <TbBrowser size={18} />;
     default:

apps/agent-tars/src/renderer/src/components/LeftSidebar/Settings/searchUtils.tsx

@@ -19,6 +19,7 @@ import {
   DuckDuckGoSearchOptions,
 } from '@agent-infra/duckduckgo-search';
 import { TavilySearchConfig, TavilySearchOptions, tavily } from './tavily';
+import { SearXNGSearchConfig, SearXNGSearchOptions, searxng } from './searxng';
 
 /**
  * Supported search providers
@@ -40,13 +41,18 @@ export enum SearchProvider {
    * Duckduckgo Search API
    */
   DuckduckgoSearch,
+  /**
+   * SearXNG Search API
+   */
+  SearXNG,
 }
 
 export interface SearchProviderConfigMap {
   [SearchProvider.BrowserSearch]: BrowserSearchConfig;
   [SearchProvider.BingSearch]: BingSearchConfig;
   [SearchProvider.Tavily]: TavilySearchConfig;
   [SearchProvider.DuckduckgoSearch]: DuckDuckGoSearchClientConfig;
+  [SearchProvider.SearXNG]: SearXNGSearchConfig;
 }
 
 export type SearchProviderConfig<T> = T extends SearchProvider
@@ -58,6 +64,7 @@ export interface SearchProviderSearchOptionsMap {
   [SearchProvider.BingSearch]: BingSearchOptions;
   [SearchProvider.Tavily]: TavilySearchOptions;
   [SearchProvider.DuckduckgoSearch]: DuckDuckGoSearchOptions;
+  [SearchProvider.SearXNG]: SearXNGSearchOptions;
 }
 
 export type SearchProviderSearchOptions<T> = T extends SearchProvider
@@ -196,6 +203,26 @@ export class SearchClient<T extends SearchProvider> {
         };
       }
 
+      case SearchProvider.SearXNG: {
+        const client = searxng(
+          this.config.providerConfig as SearXNGSearchConfig,
+        );
+        const searchOptions: SearXNGSearchOptions = {
+          count: options.count,
+          ...((originalOptions as SearXNGSearchOptions) || {}),
+          query: options.query,
+        };
+
+        const response = await client.search(options.query, searchOptions);
+        return {
+          pages: (response.results || []).map((item) => ({
+            title: item.title || '',
+            url: item.url,
+            content: item.content,
+          })),
+        };
+      }
+
       case SearchProvider.DuckduckgoSearch: {
         const client = new DuckDuckGoSearchClient(
           this.config.providerConfig as DuckDuckGoSearchClientConfig,

packages/agent-infra/search/search/src/index.ts

@@ -0,0 +1,96 @@
+/**
+ * Copyright (c) 2025 Bytedance, Inc. and its affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import fetch from 'node-fetch';
+
+export interface SearXNGSearchConfig {
+  baseUrl?: string;
+}
+
+export interface SearXNGSearchOptions {
+  query: string;
+  count?: number;
+  language?: string;
+  categories?: string[];
+  time_range?: string;
+  safesearch?: 0 | 1 | 2; // 0: close, 1: mid, 2: high
+}
+
+export interface SearXNGSearchResult {
+  title: string;
+  url: string;
+  content: string;
+  engine?: string;
+  score?: number;
+}
+
+export interface SearXNGSearchResponse {
+  query: string;
+  results: SearXNGSearchResult[];
+}
+
+export const searxng = (config: SearXNGSearchConfig = {}) => {
+  const { baseUrl = 'https://127.0.0.1:8081' } = config;
+
+  const search = async (
+    query: string,
+    options: Partial<SearXNGSearchOptions> = {},
+  ): Promise<SearXNGSearchResponse> => {
+    const {
+      count = 10,
+      language = 'zh-CN',
+      categories = ['general'],
+      time_range,
+      safesearch = 1,
+    } = options;
+
+    try {
+      const params = new URLSearchParams({
+        q: query,
+        format: 'json',
+        language,
+        categories: categories.join(','),
+        safesearch: safesearch.toString(),
+        count: count.toString(),
+      });
+
+      if (time_range) {
+        params.append('time_range', time_range);
+      }
+
+      const response = await fetch(`${baseUrl}/search?${params.toString()}`, {
+        method: 'GET',
+        headers: {
+          Accept: 'application/json',
+        },
+      });
+
+      if (!response.ok) {
+        throw new Error(
+          `SearXNG search failed with status: ${response.status}`,
+        );
+      }
+
+      const data = await response.json();
+
+      return {
+        query,
+        results: data.results
+          .map((result: any) => ({
+            title: result.title || '',
+            url: result.url || '',
+            content: result.content || result.snippet || '',
+            engine: result.engine,
+            score: result.score,
+          }))
+          .slice(0, count),
+      };
+    } catch (error) {
+      console.error('SearXNG search error:', error);
+      throw error;
+    }
+  };
+
+  return { search };
+};

packages/agent-infra/search/search/src/searxng.ts

@@ -24,6 +24,7 @@ export enum SearchProvider {
   TAVILY = 'tavily',
   DUCKDUCKGO_SEARCH = 'duckduckgo_search',
   BROWSER_SEARCH = 'browser_search',
+  SEARXNG = 'searxng',
 }
 
 export interface SearchSettings {