How to Add a New Web Search Provider to WeKnora: Complete Integration Guide

To add a new web search provider to WeKnora, you must register a WebSearchProviderEntity in the backend database, expose it via the API endpoint, map a logo and ProviderCategory in the frontend configuration, and ensure the agentWebSearch.ts utility can read the web_search_provider_id from the client settings.

Tencent/WeKnora implements a modular provider architecture for web search capabilities. The system standardizes search integrations through the WebSearchProviderEntity type defined in frontend/src/api/web-search-provider.ts, allowing the frontend to dynamically render provider options and route queries through the configured backend endpoint. When web_search_enabled is set to true, the application uses web_search_provider_id to determine which search engine handles the request.

Understanding the Web Search Architecture

WeKnora's provider system consists of three integrated layers. The backend persists provider metadata in the web_search_providers table and exposes it through the server configuration. The frontend consumes this data via the settings store, while frontend/src/utils/agentWebSearch.ts provides the logic checks—specifically shouldDoWebSearch() and getWebSearchProviderId()—that determine whether to invoke web search and which provider ID to pass to the API.

Step 1: Register the Provider in the Backend

First, persist the new provider definition in the database. This record must include a unique identifier, display metadata, API endpoint, and the category classification.

INSERT INTO web_search_providers (
  id, 
  name, 
  description, 
  endpoint, 
  category, 
  logo_url
) VALUES (
  'my_custom_search', 
  'My Custom Search', 
  'High-performance privacy-focused search API', 
  'https://api.customsearch.com/v1', 
  'websearch',
  '/provider-logos/my_custom_search.svg'
);

Step 2: Expose the Provider via the API

The frontend expects provider objects to conform to the WebSearchProviderEntity interface declared in frontend/src/api/web-search-provider.ts. Ensure your backend handler for /api/web-search-provider returns an array of objects matching this schema, including id, name, description, endpoint, and category fields.

Step 3: Configure Server-Side Settings

In packages/dsh-weknora/src/config.ts, verify that the server loads the provider list into the global settings store at startup. This makes the registry available to the frontend through the initial configuration payload.

// packages/dsh-weknora/src/config.ts
export interface WebSearchProvider {
  id: string;
  name: string;
  description: string;
  endpoint: string;
  category: ProviderCategory;
  logo_url: string;
}

// Load providers into the settings store
settingsStore.webSearchProviders = await db.select<WebSearchProvider>('web_search_providers');

Step 4: Add Provider Branding and Category

Update frontend/src/views/settings/providerLogos.ts to include the visual assets for your new provider. The ProviderCategory type defines valid classifications including 'websearch', 'vectorstore', 'storage', 'parser', and 'sandbox'.

// frontend/src/views/settings/providerLogos.ts
export type ProviderCategory = 'vectorstore' | 'storage' | 'websearch' | 'parser' | 'sandbox';

export const providerLogos: Record<string, { category: ProviderCategory; logo: string }> = {
  my_custom_search: { 
    category: 'websearch', 
    logo: '/provider-logos/my_custom_search.svg' 
  },
  // ... existing entries
};

Step 5: Update the Frontend Selector

The UI component—typically BrowserSearchPreferences.vue or an equivalent settings view—reads available providers from the settings store. The utility functions in frontend/src/utils/agentWebSearch.ts handle the configuration detection.

// frontend/src/utils/agentWebSearch.ts
import type { WebSearchProviderEntity } from '@/api/web-search-provider';

export function shouldDoWebSearch(config?: { 
  web_search_enabled?: boolean; 
  web_search_provider_id?: string 
}) {
  return config?.web_search_enabled === true;
}

export function getWebSearchProviderId(config?: { 
  web_search_provider_id?: string 
}) {
  const explicitId = config?.web_search_provider_id?.trim();
  return explicitId ?? '';
}

The Vue template automatically renders the new provider because it binds to the reactive store populated by the configuration loader.

<template>
  <select v-model="selectedProviderId">
    <option 
      v-for="provider in webSearchProviders" 
      :key="provider.id" 
      :value="provider.id"
    >
      {{ provider.name }}
    </option>
  </select>
</template>

<script setup lang="ts">
import { ref, watch } from 'vue';
import { useSettingsStore } from '@/stores/settings';

const store = useSettingsStore();
const webSearchProviders = store.webSearchProviders;
const selectedProviderId = ref(store.web_search_provider_id);

watch(selectedProviderId, (newId) => {
  store.updateWebSearchProviderId(newId);
});
</script>

Verifying the Integration

Test the implementation by enabling web search in the application settings and selecting your new provider. Trigger a search operation and inspect the network request payload to confirm it contains the correct web_search_provider_id. Verify that the response returns results from your configured endpoint and that the UI displays the provider logo correctly in the selector dropdown.

Summary

• The WebSearchProviderEntity type in frontend/src/api/web-search-provider.ts defines the contract between the backend registry and frontend components.
• New providers require an entry in the web_search_providers database table with a unique ID and valid ProviderCategory.
• The providerLogos.ts file maps provider IDs to logo assets and must be updated to include new visual resources.
• frontend/src/utils/agentWebSearch.ts provides shouldDoWebSearch() and getWebSearchProviderId() to determine whether to execute a search and which provider to target.
• Server configuration in packages/dsh-weknora/src/config.ts loads the provider registry into the settings store for frontend consumption.

Frequently Asked Questions

Where is the provider list stored in WeKnora?

The provider list is stored in the web_search_providers database table (or equivalent backend configuration file) and cached in the server-side settings store defined in packages/dsh-weknora/src/config.ts. The frontend retrieves this list through the API and stores it in the reactive settings store.

What is the WebSearchProviderEntity type used for?

WebSearchProviderEntity is the TypeScript interface that standardizes the shape of search provider objects across the WeKnora stack. It ensures that the backend, API layer, and frontend components all agree on the required fields—such as id, name, endpoint, and category—preventing type mismatches when rendering provider options or building search requests.

How does the frontend determine which web search provider to use?

The frontend checks the web_search_enabled boolean and retrieves the web_search_provider_id string from the configuration object. These values are processed by the utility functions in frontend/src/utils/agentWebSearch.ts, specifically getWebSearchProviderId(), which returns the provider ID to include in API requests. If no ID is specified, the function returns an empty string, and the backend typically falls back to a default provider.

Do I need to modify the API contract to add a new provider?

No, you do not need to modify the API contract if your new provider conforms to the existing WebSearchProviderEntity schema. Simply adding the provider record to the backend database and ensuring the /api/web-search-provider endpoint returns it is sufficient. Only modify frontend/src/api/web-search-provider.ts if you need to add custom fields that do not exist in the current type definition.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}