dsh-web-search-tavily
A DeepSeek Harness (dsh) plugin that
provides web search through the Tavily Search API.
Requires dsh >= 0.1.5-rc.2 — this plugin targets the dsh RC/stable line only (CI and releases resolve the newest of the latest/next dist-tags at runtime). The alpha line is no longer supported.
It replaces the default DeepSeek web search — which spends a full auxiliary model call
per search (Anthropic-compatible Messages API + web_search_20250305 server tool) —
with a plain Tavily REST call: ~1s, 1 credit at basic depth, no model tokens.
The plugin registers a WebSearchProvider (id: "tavily") with the official
ctx.web capability seam,
so everything around the tool stays exactly as shipped: the model still calls the same
web_search tool, with the same citation formatting, searchMaxResults bound, and
timeout budget. A provider swap changes how the harness reaches the web, nothing else.
Requirements
- dsh
>= 0.1.5-rc.2 (peer deps resolve to the profile's shared @deepseek-ai closure)
- A Tavily API key (
tvly-…, free tier available)
Install
One command:
dsh plugin --profile <name> add @aiwayds/dsh-web-search-tavily
dsh plugin installs the package into the profile (via pnpm) and registers it in
dsh.profile.bundles automatically. Restart dsh — the provider is registered and ready.
Local development: dsh plugin --profile <name> add link:/path/to/dsh-web-search-tavily
(relative path specs anchor to your invoking directory). The manual route — adding the
dependency and the bundle entry to ~/.dsh/profiles/<name>/package.json yourself and
running pnpm install there — works identically.
Unlike the anysearch sibling plugin, this one does not claim the web_search
default on install — Tavily needs an API key, and a selected-but-unconfigured provider
would fail every search. After storing the key, select it with one patch entry (below).
@deepseek-ai/* packages are peer dependencies by design: they must resolve to
the profile's single shared dsh closure (link-dsh-closure). Putting them in
dependencies installs a second cordis instance and crashes the loader.
Uninstall
dsh plugin --profile <name> remove @aiwayds/dsh-web-search-tavily
The host auto-cleans the whole install: the bundles entry is spliced out of the
profile's package.json, the dependency is removed, and the plugin's patch
layer drops with the package. Restart dsh and the tavily provider is gone —
web_search falls back to whichever provider your patch layers still select
(the shipped deepseek-official by default).
The plugin keeps no on-disk state. Your Tavily API key lives in host-owned
storage — the TAVILY_API_KEY ref in ~/.dsh/.credentials.yaml or the
launching environment — and uninstall never touches it. If you no longer want
the key (or the searchProvider: tavily patch entry selecting the provider),
remove those by hand.
Configure
1. API key. Store the key in dsh's managed credentials document
(~/.dsh/.credentials.yaml) — resolved per search, never written to config files:
version: 1
refs:
TAVILY_API_KEY: tvly-xxxxxxxx
Fallbacks, in resolution order: TAVILY_API_KEY in the launching environment, then a
literal apiKey in the plugin config (discouraged).
2. Select the provider. The base bundle pins web.searchProvider to
deepseek-official, and a configured id always wins — so add the override to the
profile's cordis.patch.yml (or the home-level ~/.dsh/cordis.patch.yml for every
profile):
- id: web
config:
searchProvider: tavily
Optionally retire the DeepSeek search plugin entirely:
- id: web-search-deepseek
disabled: true
Restart dsh. Verify the composed tree:
dsh --profile <name> --dump-config | grep -A3 'id: web$' # searchProvider: tavily
Rollback: delete the patch entries and restart — web_search returns to the
shipped DeepSeek provider.
Plugin config (all optional; via a patch layer, read at startup):
| Field | Default | Notes |
|---|
apiKeyEnv | TAVILY_API_KEY | Credential reference resolved per search |
apiKey | — | Literal key; wins over the reference |
baseURL | https://api.tavily.com | Env override: TAVILY_BASE_URL |
searchDepth | basic | basic / advanced (2 credits) / fast / ultra-fast |
topic | general | general / news / finance |
maxResults | 8 | Default when the tool sends no bound; API caps at 20 |
includeAnswer | true | Tavily's generated answer becomes the result's content |
Example patch entry with config:
- insert:
- id: web-search-tavily
name: '@aiwayds/dsh-web-search-tavily'
config:
searchDepth: advanced
topic: news
Behavior
results[].content → the portable snippet; Tavily's answer → the result's
content; the API returns no publication dates, so publishedAt is never set.- Follows the
ctx.web seam contract: cancellation as WEB_ABORTED, a missing key as
WEB_PROVIDER_CREDENTIAL_MISSING (naming TAVILY_API_KEY), provider failures as
WEB_PROVIDER_ERROR with Tavily's own error detail surfaced; a rejected key reads
Tavily rejected the API key (HTTP 401).
available() is a local check only (credential source present, base URL parseable) —
it never makes network calls.- Result-count requests are clamped to Tavily's
max_results cap (20); the seam
additionally enforces the tool's searchMaxResults bound (default 8).
Develop
npm install
npm run check # tsc --noEmit
npm test # build + node --test (14 tests)
After editing src/, run npm run build and restart dsh — the plugin loads from
lib/. Unit tests cover response mapping, availability, the request shape, and the
HTTP/abort/credential error branches with mocked fetch.
License
MIT
