All plugins

web-serply

Serply web search provider for Hermes Agent. Google web results via the Serply SERP API. Requires SERPLY_API_KEY (sign up at https://serply.io).

serply-incWebv1.0.0Updated 1 month ago

hermes-web-serply

A Serply web search provider plugin for
Hermes Agent.

Registers serply as a web_search backend, so the agent answers from live Google
results instead of from memory. Search only: pair it with Firecrawl, Tavily or Exa if
you also want web_extract.

Install

hermes plugins install web-serply

Or clone into your user plugin directory and enable it:

git clone https://github.com/serply-inc/hermes-web-serply ~/.hermes/plugins/web/serply
hermes plugins enable web-serply

Configure

Get an API key at serply.io, then set it in your shell or in
~/.hermes/.env:

export SERPLY_API_KEY="your-key"

Select Serply as the search backend with hermes tools, or set it directly in
~/.hermes/config.yaml:

web:
  search_backend: "serply"

web.backend: "serply" also works as the shared fallback when search_backend is
unset.

Environment variables

| Variable | Required | Purpose |
|---|---|---|
| SERPLY_API_KEY | yes | API key, from serply.io |
| SERPLY_API_URL | no | Base URL override, defaults to https://api.serply.io |

Behaviour

  • Calls GET /v1/search with q and num, authenticated with the X-Api-Key header.
  • Requests at most 10 results. Serply caps a single response at 10 and ignores a
    larger num, so the plugin clamps rather than promising more than arrives.
  • Returns the fixed Hermes envelope,
    {"success": true, "data": {"web": [{"title", "url", "description", "position"}]}},
    with position being the rank among the rows returned.
  • On failure returns {"success": false, "error": ...}, surfacing Serply's own
    detail message so an invalid or exhausted key explains itself to the model.
  • Sends User-Agent: hermes-agent so Serply can attribute traffic to this
    integration.

Scope

Serply also serves News (tbm=nws) and Google Scholar (/v1/scholar), but the Hermes
WebSearchProvider interface passes only query and limit, with no vertical to
route on. This plugin therefore serves Google web results. If that interface grows a
topic parameter, the other verticals are a small addition here.

Pricing

Serply starts with 2,500 free credits and then uses prepaid packs; credits do not
expire. Current pricing is at serply.io, and the API is
documented at serply.io/docs.

Development

The plugin is three files: plugin.yaml (manifest), provider.py
(SerplyWebSearchProvider, a WebSearchProvider subclass) and __init__.py
(register()). It depends only on httpx, which Hermes already ships, so there is
no SDK to install.

See the Hermes
web search provider plugin guide
for the provider contract.

License

MIT, see LICENSE.

Maintained by Serply.

README from the reviewed commit c6cab41; it updates when the author re-pins.