serpkite

serpkite-hermes-plugin

A SerpKite web search provider plugin for
Hermes Agent.

It registers serpkite as a backend for both web tools:

• web_search returns live Google web results from SerpKite's /v1/search.
• web_extract returns pages as Markdown from SerpKite's /v1/webpage. Pages that
  need JavaScript are rendered in a browser, and PDFs are read from their text layer.

Install

From the Hermes plugin catalog:

hermes plugins install serpkite --enable

Or from the repository:

hermes plugins install SerpKite/serpkite-hermes-plugin --enable

Hermes installs third-party plugins disabled unless you pass --enable or answer
yes at the prompt. To enable it later, run hermes plugins enable serpkite.

Configure

Create an API key at app.serpkite.com/keys, then set it
in your shell or in ~/.hermes/.env:

export SERPKITE_API_KEY="skt_live_..."

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

web:
  backend: "serpkite"          # search and extract

To use it for one capability only:

web:
  search_backend: "serpkite"
  extract_backend: "firecrawl"  # or any other extract backend

Environment variables

| Variable | Required | Purpose |
|---|---|---|
| SERPKITE_API_KEY | yes | API key, from app.serpkite.com/keys |
| SERPKITE_API_URL | no | Base URL override, defaults to https://api.serpkite.com |

Pricing

A new account gets 2,500 free credits (1,000 when you verify your email, 1,500 more
when you link GitHub or Google), then 1,000 free credits each month. A search costs
1 credit and a page extract costs 1 credit. Failed, empty and blocked requests
are not billed. Paid credit packs and current prices are at
serpkite.com/pricing.

Behaviour

• Search calls POST /v1/search with {"q": <query>, "num": <n>}, where n is the
  requested limit capped at 10. One request is one Google results page, so a search
  never costs more than 1 credit.
• Results map to the Hermes row shape {"title", "url", "description", "position"}:
  url is SerpKite's resolved link, description its snippet, and position the
  rank among the rows returned.
• Extract calls POST /v1/webpage with {"url": <url>} once per URL, up to 4 at a time.
  Content is the page Markdown (or the raw HTML when Hermes asks for format="html").
  When a page redirects, the entry's url is the final URL and metadata.sourceURL the
  URL that was asked for.
• Every request sends Authorization: Bearer <key> and
  User-Agent: serpkite-hermes-plugin/<version>.
• Errors come back as {"success": false, "error": ...} for search and as per-URL
  error entries for extract. The text carries SerpKite's error code, message and
  request id, for example
  SerpKite API error 402 insufficient_credits: ... (request_id req_...).
  Rate limits (429) and upstream failures (503) are marked as not billed and retryable.
• The plugin does not log query text.

The Hermes web_search interface passes only a query and a limit, so country,
language and time filters are not set: searches use SerpKite's defaults (us, en).

Privacy and network use

The plugin sends the agent's search queries and the URLs it extracts to
api.serpkite.com, authenticated with SERPKITE_API_KEY. It makes no other network
calls, reads no files, runs no shell commands or background processes, and stores
nothing. See the SerpKite privacy policy for how the
API handles requests.

Development

The plugin is three files: plugin.yaml (manifest), provider.py
(SerpKiteWebSearchProvider, a WebSearchProvider subclass) and __init__.py
(register()). It depends only on httpx, which Hermes already ships.

Tests mock HTTP (no network) and need agent.web_search_provider importable. Run them
with the Python of a Hermes test environment (built per Hermes's CONTRIBUTING.md with
python -m pm.build_env --source . --out .venv --group dev --group test):

HERMES_AGENT_PATH=/path/to/hermes-agent \
  /path/to/hermes-agent/.venv/bin/python -m pytest tests

Validate the plugin the way the Hermes plugin catalog does:

hermes plugins validate /path/to/serpkite-hermes-plugin --install-deps

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

License

MIT, see LICENSE.

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