Introduction

When developing agents with DeepSeek Harness (DSH), a single search source may fail due to timeouts, quota exhaustion, or service outages. The dsh-web-search-router plugin provides a prioritized multi-provider router with built-in automatic fallback, designed to address the instability of a single search source.

What It Is

This is a multi-provider web_search routing plugin for DSH, maintained by developer Kerberos255. It registers a DSH web search provider named web-search-router, while keeping the tool exposed to the model unchanged: agents still invoke DSH’s built-in web_search. The plugin tries the configured providers in order and stops at the first successful result.

Core Features

  • Provider Management: The DSH settings interface allows adjusting provider priority order and enabling or disabling specific providers.
  • Automatic Fallback: The plugin automatically switches to the next provider when configuration is missing, a provider fails, times out, hits rate limits, exhausts quota, or, by default, when results are empty.
  • Cooldown Mechanism: Short cooldowns are set for transient failures; cooldowns are configurable for rate limit and quota issues.
  • Configuration and Security: Non-sensitive settings are stored in the DSH native settings namespace and take effect without a restart. API keys remain in DSH credentials or the launch environment and are not displayed in the settings interface.
  • Log Sanitization: Provider error messages are sanitized before being logged or returned through the router, with sensitive data removed.

Installation and Activation

Install the plugin via the command line. It is recommended to pin a specific commit hash or tag to ensure compatibility:

dsh plugin --profile web add github:Kerberos255/dsh-web-search-router#<commit-or-tag>

After installation, the plugin automatically selects web-search-router as the DSH search provider and injects default configuration.

Typical Usage

  • Prerequisites: Your agent preset must expose DSH’s built-in web_search tool (for example, a standard preset). If web_search is omitted from the preset, the router will not be invoked.

  • Settings Configuration: Navigate to Settings → Plugins → Plugin configuration → Web Search Router.

    • On this page, you can reorder providers, enable or disable providers.
    • Configure the base URL for SearXNG (no API key required).
    • Set or clear API keys for each provider.
    • Set timeouts and cooldowns for each provider.
    • Choose whether to continue trying the next provider when results are empty.

  • Provider List: The plugin supports multiple search sources, including SearXNG, DeepSeek Search, Tavily, Brave Search, Exa, Firecrawl, Parallel, and DuckDuckGo. Unconfigured providers are automatically skipped.

  • Advanced DeepSeek Search Configuration: The plugin uses DSH’s official DeepSeek search provider settings by default. You can override them in the configuration file, for example by specifying a custom deepseekBaseURL, deepseekModel, or the environment variable deepseekApiKeyEnv.

Fallback Behavior Logic

For each enabled provider, the following steps are performed:
1. Check whether it is configured or currently in a cooldown period; otherwise, skip it.
2. Run the search using the configured timeout.
3. If successful, return the result immediately.
4. If the result is empty (depending on the configuration), continue to the next provider.
5. If it fails, classify the error and continue to the next provider.

Note: A caller abort propagates immediately and does not trigger the fallback mechanism.

Notes and Compatibility

  • DSH Version: Currently compatible with DSH 0.1.0-rc.6 and 0.1.1-rc.x; the runtime requires Node.js 20+. DeepSeek Harness is still in developer preview, so check compatibility carefully when upgrading.
  • Security: Credential values are resolved on the host only. The browser receives only credential references and configuration status metadata, and does not store key values. Router error logs first mask URLs and key/token-like values.

Summary

dsh-web-search-router provides DSH with a flexible and reliable search backend solution. Through multi-source routing and automatic fault tolerance, it enhances the stability of agents retrieving web information. For more details, refer to the GitHub repository or the community directory.