dsh-plugin-web-search-tavily — Tavily backend for dsh's built-in web_search
Install · Config · Behavior · Model Experience · 中文文档
A community Tavily search provider for DeepSeek Harness (dsh). It registers a WebSearchProvider into the ctx.web capability seam, so the shipped web_search tool can be served by Tavily without touching any model-facing schema.
Ships as a dsh bundle: installing it into a profile inserts its plugin row automatically.
Install
dsh plugin --profile web add dsh-plugin-web-search-tavily
Provide the API key through the environment (TAVILY_API_KEY, e.g. in $DSH_HOME/.env) or through plugin config. When more than one search provider is usable in your composition, pin the selection with $DSH_WEB_SEARCH_PROVIDER=tavily or by patching the web row's searchProvider in your profile's cordis.patch.yml; with Tavily as the only usable provider, selection is automatic.
Verify without booting, then boot:
dsh --profile web --dump-config # shows a "# == dsh-plugin-web-search-tavily" layer
dsh --profile web
Config
Override any field by patching the web-search-tavily row in your profile's cordis.patch.yml (a patch replaces the whole config value — restate the fields you keep):
| Key | Default | Meaning |
|---|
apiKey | $TAVILY_API_KEY | Tavily API key. Empty makes the provider registered-but-unavailable. |
baseURL | https://api.tavily.com | Endpoint base; /search is appended. |
searchDepth | basic | Tavily search_depth. advanced returns richer snippets at extra credit cost. |
topic | general | Tavily topic vertical (general or news; news populates publishedAt). |
includeAnswer | true | Request Tavily's generated answer; it surfaces as the search result's content. |
numResults | (omitted) | Default result count when a request carries no maxResults. The seam still enforces the tool-layer bound either way. |
- id: web-search-tavily
config:
searchDepth: advanced
includeAnswer: false
Behavior
POST {baseURL}/search with Authorization: Bearer <key>, honoring the request AbortSignal; redirects are refused.results[].content maps to snippet, published_date to publishedAt; entries without a non-blank snippet are dropped rather than padded with invented text.- A non-blank
answer maps to the result's content; nothing is fabricated when Tavily returns none.
- Cancellation surfaces as
WebError code WEB_ABORTED; every other failure (transport, non-2xx, unprocessable body) is WEB_PROVIDER_ERROR with the richest provider detail available and a preserved cause chain. A non-2xx JSON error body's detail.error / detail / error / message fields are tried in that order.
available() is a cheap local check (key present, base URL parseable, bounds valid) and never touches the network.
Model Experience
What the model sees
Nothing from this package directly. The model-facing web_search schema and rendering belong to @deepseek-ai/dsh-tool-web; this provider only changes which backend serves the call. Result content (Tavily's generated answer, when enabled) and per-source title/snippet/publishedAt flow through the tool's ordinary rendering.
Token effect
includeAnswer: true adds one provider-generated answer paragraph to each search result the model reads. searchDepth: advanced tends to return longer snippets. Both are provider-output effects; the tool-layer maxResults bound is enforced by the seam regardless of provider.
KV Cache effect
None. Search results enter the conversation as ordinary tool results; this package contributes no prompt sections and changes no request prefix.
Development
npm install
npm run build
npm test # keyless: loopback double asserts wire shape and error taxonomy
TAVILY_API_KEY=tvly-... npm test # adds the live smoke (self-skips without the key)
Keyless tests drive the real provider against a loopback HTTP double and assert the exact request shape (method, path, bearer header, user-agent, body fields), response mapping, the error taxonomy, and cancellation. The live smoke verifies the wire contract against the real API and self-skips without a key; it last passed against the live Tavily API at v0.1.1 (2026-08).
Known Limitations and Deferred Work
- The Tavily wire contract is pinned to its 2026-08 public documentation. Field names (
search_depth, include_answer, max_results) are this package's responsibility to track; the live smoke is the drift detector, last green against the live API at v0.1.1.
include_domains / exclude_domains / days are not exposed. The seam's request carries only query and maxResults today; domain filtering would be provider config rather than a per-call control, and no consumer has asked for it yet.- No retry policy. A transient Tavily failure surfaces as one
WEB_PROVIDER_ERROR; retrying is left to the caller or a future seam-level policy, matching the in-tree providers.
- dsh is in developer preview. This package pins
@deepseek-ai/dsh-web to the currently published pre-release; expect lockstep bumps while upstream iterates.
License
MIT
