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

> Learn how to add a new web search provider to WeKnora. This guide covers backend registration, API exposure, frontend mapping, and utility configuration for seamless integration.

- Repository: [Tencent/WeKnora](https://github.com/tencent/WeKnora)
- Tags: how-to-guide
- Published: 2026-09-13

---

**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`](https://github.com/Tencent/WeKnora/blob/main/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`](https://github.com/Tencent/WeKnora/blob/main/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`](https://github.com/Tencent/WeKnora/blob/main/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.

```sql
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`](https://github.com/Tencent/WeKnora/blob/main/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`](https://github.com/Tencent/WeKnora/blob/main/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.

```typescript
// 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`](https://github.com/Tencent/WeKnora/blob/main/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'`.

```typescript
// 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`](https://github.com/Tencent/WeKnora/blob/main/BrowserSearchPreferences.vue) or an equivalent settings view—reads available providers from the settings store. The utility functions in [`frontend/src/utils/agentWebSearch.ts`](https://github.com/Tencent/WeKnora/blob/main/frontend/src/utils/agentWebSearch.ts) handle the configuration detection.

```typescript
// 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.

```vue
<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`](https://github.com/Tencent/WeKnora/blob/main/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`](https://github.com/Tencent/WeKnora/blob/main/providerLogos.ts) file maps provider IDs to logo assets and must be updated to include new visual resources.
- [`frontend/src/utils/agentWebSearch.ts`](https://github.com/Tencent/WeKnora/blob/main/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`](https://github.com/Tencent/WeKnora/blob/main/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`](https://github.com/Tencent/WeKnora/blob/main/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`](https://github.com/Tencent/WeKnora/blob/main/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`](https://github.com/Tencent/WeKnora/blob/main/frontend/src/api/web-search-provider.ts) if you need to add custom fields that do not exist in the current type definition.