v1.0.0 — Free Google Search for Hermes Agent, no API key

🔍 v0.1.0 — Free Google Search for Hermes Agent, no API key

v1.0.0 is the first public release of SuearchHermes — a drop-in WebSearchProvider plugin for Hermes Agent that routes every web_search call through Google's own Antigravity CLI (agy). No API key. No billing. No DuckDuckGo. Real Google results, synthesized by Gemini, with cited source domains.

This release ships the plugin, a one-command installer, automatic config.yaml wiring, and full documentation.

git clone https://github.com/leonardo-ferioli/SuearchHermes.git
cd SuearchHermes
./install.sh

Highlights

🔍 Real Google Search, not scraping

Every other free web_search backend in Hermes scrapes DuckDuckGo's HTML or Brave's limited free tier. SuearchHermes calls agy -p under the hood, which uses Google Search Grounding via Gemini — the same grounding API that powers Gemini's own "search the web" capability. The model reads the results, synthesizes a concise answer, and returns source domains. You get an answer, not a list of links to read yourself.

🆓 Zero cost, zero API keys

The plugin uses your existing agy OAuth session — the one you already created when you ran agy and logged in with your Google account. No BRAVE_SEARCH_API_KEY, no TAVILY_API_KEY, no FIRECRAWL_API_KEY, no credit card, no Cloud Console. If agy works on your machine, SuearchHermes works.

🔌 Drop-in Hermes plugin

SuearchHermes implements Hermes' WebSearchProvider ABC — the same interface that ddgs, brave-free, firecrawl, tavily, exa, parallel, and searxng implement. It lives at ~/.hermes/hermes-agent/plugins/web/agy/ and registers itself at import time. Hermes' web_search tool dispatches to it automatically once config.yaml points at search_backend: agy. No monkey-patching, no fork, no core edits.

⚡ One-command install

./install.sh does three things:

1. Copies plugins/web/agy/ into ~/.hermes/hermes-agent/plugins/web/agy/
2. Verifies agy is installed at ~/.local/bin/agy (warns if not)
3. Prepends web:\n search_backend: agy\n to ~/.hermes/config.yaml if no search_backend is set

Then restart Hermes and every web_search call goes through Google.

🌐 Clean source domains, not redirect URLs

Gemini's grounding API returns vertexaisearch.cloud.google.com/grounding-api-redirect/... URLs by default — opaque redirects that tell you nothing. SuearchHermes' prompt engineering asks agy to return source domain names instead (github.com, rust-lang.org, reddit.com), so the agent and the user see readable, meaningful sources.

🏛️ Architecture

~/.hermes/hermes-agent/plugins/web/agy/
├── __init__.py     # register(ctx) → registers AgYWebSearchProvider
└── provider.py     # AgYWebSearchProvider: search() calls agy -p

The plugin normalizes agy's text output into Hermes' expected JSON shape:

{
  "success": true,
  "data": {
    "web": [
      {"title": "...", "url": "...", "description": "...", "position": 1}
    ]
  }
}

📋 Requirements

Requirement	Version	Notes
Hermes Agent	any (with plugin system)	~/.hermes/hermes-agent/
Antigravity CLI	1.1.0+	curl -fsSL https://antigravity.google/cli/install.sh | bash
Python	3.10+	comes with Hermes
OS	Linux, macOS	wherever agy runs

📊 Numbers at v1.0.0

• 1 plugin file pair (__init__.py + provider.py)
• 1 installer script
• 0 API keys required
• 0 dollars per month
• 1 Google account (yours, already authenticated)
• 120 second search timeout (configurable in provider.py)

---

Full docs: README.md

---

MIT License — Leonardo Ferioli