web.search_backend / web.extract_backend default to empty strings, silently no-op web_search / web_extract even when web.backend and the provider API key are set

Affected: Hermes Agent installed via per-user installer on Ubuntu 24.04, main HEAD as of 2026-05-20.

Summary

When a user sets web.backend: tavily in ~/.hermes/config.yaml and exports TAVILY_API_KEY in ~/.hermes/.env, the natural assumption (mine, anyway) is that web_search and web_extract are now wired. They are not. Both tools are gated on web.search_backend and web.extract_backend, both of which default to empty strings. When the agent invokes web_search, the tool quietly returns nothing — no error, no warning, no log line indicating the backend was unset.

This is the same class of bug as #28863 (docker_extra_args silently dropped from config.yaml): a config key that looks set is in fact disabled by an unrelated empty-string default, with no startup warning.

#21003 is adjacent but different — that issue asks whether per-task backends are supported. They are; this issue is about the default being unusable.

Reproduction

1. Fresh Hermes install on a VPS. Tavily API key obtained from tavily.com and exported in .env:

   echo "TAVILY_API_KEY=tvly-..." >> ~/.hermes/.env

2. Set web.backend in ~/.hermes/config.yaml:

   web:
     backend: tavily
     # search_backend and extract_backend left at their installer defaults (empty strings)

3. Restart the gateway.
4. From the agent (Telegram, CLI, anywhere), prompt: "Use web_search to find one recent article about X. Reply with the URL."

Expected: web_search returns Tavily results and the agent cites a real URL.

Actual: The agent either:

• Skips web_search entirely (which it may rationalize as "I already know enough") and produces a synthesis with no citations; or
• Calls web_search, receives nothing meaningful, and writes around the absence without flagging it.

No warning is logged. No error is raised. The user has no signal that the configured backend is not being used.

Root cause hypothesis

~/.hermes/config.yaml (installer-default values shown):

web:
  backend: tavily
  search_backend: ''        # ← silently disables web_search
  extract_backend: ''       # ← silently disables web_extract
  use_gateway: false

The per-task search_backend and extract_backend keys appear to override web.backend rather than fall back to it. With both at empty strings (the installer default), the per-task backends resolve to "no provider," and the web tools fail closed without a diagnostic.

Fix

Three options, in order of robustness:

1. Make web.search_backend and web.extract_backend default to the value of web.backend when empty. Most users who set web.backend plus an API key expect both tools to work; this matches that mental model and eliminates the gotcha entirely.
2. Warn at gateway startup when web.backend and a provider API key are set but per-task backends are empty. Lower-cost change; preserves explicit-only configuration for users who want it.
3. Surface the empty backend in the failing tool call itself ("web_search is configured with search_backend='' — no provider will be called"). Useful diagnostic even if (1) or (2) lands.

Why this matters

web_search is one of the most-relied-on tools for any research-shaped agent task. When it silently no-ops, the model rationalizes around the absence — writes a synthesis from its own knowledge, fabricates plausible-shaped URLs, or omits citations the user asked for. The user only notices when they spot-check URLs and find none.

In my case, I was debugging an unrelated SOUL-tuning problem ("why is the agent not using web_search like I asked?") for an hour before discovering the actual problem was infrastructural. The two-line config change to fix it was trivial; finding it was the time sink.

Workaround

Set both explicitly in ~/.hermes/config.yaml:

web:
  backend: tavily
  search_backend: tavily
  extract_backend: tavily

Restart gateway. web_search and web_extract start working immediately.