Build a Hermes Web Search Provider Plugin

Connect a search or extraction backend to Hermes with explicit capability flags, normalized results, and independent search/extract routing. This guide focuses on the public implementation contract; the official Hermes documentation remains the source of truth as interfaces evolve.

How the interface works

A web provider may support search, extraction, or both. web.search_backend and web.extract_backend can select different providers, while web.backend is the shared fallback.

Registration uses ctx.register_web_search_provider(...). The provider supplies a stable name, a cheap availability check, capability flags, and the corresponding search() or extract() methods.

Search results use a fixed web-result envelope; extraction returns per-URL records with URL, title, content, raw content, metadata, and optional per-item errors.

Capability flags prevent Hermes from sending extraction work to a search-only backend. Optional dependencies should be loaded lazily and remain subject to the host security setting.

Practical checklist

Decide whether the backend is search-only, extract-only, or combined.
Normalize limits and URLs before the provider call.
Map upstream output into the documented result envelope.
Return per-URL extraction failures without discarding successful siblings.
Configure and test split search/extract providers when appropriate.

Common pitfalls

Making a network request from is_available().
Reporting unsupported extraction capability and failing at runtime.
Passing raw vendor-specific response shapes through to the tool.
Importing optional SDKs at module load and breaking unrelated tools.

Verification steps

Choose the backend in hermes tools and inspect the resulting web config.
Run a bounded search and verify title, URL, description, and ordering.
Extract multiple public URLs, including one expected failure.
Confirm a search-only backend is skipped for extraction rather than producing a misleading provider error.

Official reference

https://hermes-agent.nousresearch.com/docs/developer-guide/web-search-provider-plugin