hermes-gemini-web-search 1.0.0

Live web search and content extraction for Hermes agent — powered by Google Gemini Search Grounding

Hermes Gemini Web Search

Give your Hermes agent live access to the web — powered by Google's search index, delivered through the Gemini API.

When your agent needs to look something up, this plugin answers with grounded, sourced results instead of stale training data. It works for both quick searches ("what's the latest Python release?") and deep page extraction ("summarize this RFC for me").

Why use this plugin?

Real answers from the live web. Your agent's training data ends months ago. This plugin connects it to Google Search so it can answer questions about today's world — breaking news, current docs, recent releases, real-time events.

Grounded, not guessed. Every result is backed by Google's search index. The agent sees actual search snippets and supporting sources, not hallucinations. When you ask "what changed in React 19?" you get the real changelog, not a confident-sounding fabrication.

Search and extract in one. Some providers only search. This one does both — find information and pull full page content — so you don't need two plugins wired together.

Free to start. Google offers a generous free tier. You only pay if your usage grows past it. No credit card required to get a key.

Runs on Gemini's speed. Uses gemini-3.1-flash-lite by default — fast, cheap, and purpose-built for search grounding. You can swap in any Gemini model.

Zero maintenance. The provider self-registers with Hermes at startup. There is nothing to configure beyond pasting your API key.

What you'll need

• Hermes agent installed and working (any platform — CLI, desktop, Telegram, Discord, etc.)
• A Google API key (free, takes 30 seconds)

That's it. No other accounts, no credit card, no setup scripts.

Getting a Google API key

1. Go to Google AI Studio in your browser
2. Sign in with any Google account (personal Gmail works)
3. Click "Create API Key"
4. Copy the key that appears — it will look like AIza...

The free tier gives you a generous number of queries per minute. You will get an email if you approach the limit — upgrade to a paid plan only if you need more.

Installation

One command

From inside your Hermes environment:

pip install hermes-gemini-web-search

Or from source

git clone https://github.com/your-username/hermes-gemini-web-search.git
cd hermes-gemini-web-search
pip install .

Or by copying into Hermes directly

mkdir -p ~/.hermes/plugins/web/gemini
cp hermes_gemini_web_search/* ~/.hermes/plugins/web/gemini/

The pip install method is recommended — it keeps the plugin up to date and discoverable.

Configuration

Three short steps. Everything happens in two files inside ~/.hermes/.

Step 1 — Add your API key

Open ~/.hermes/.env in any text editor and add one line:

GEMINI_API_KEY=AIza...your-key-here

You can also use GOOGLE_API_KEY if you already have one set for other Google services. The plugin checks both.

Step 2 — Enable the plugin

Open ~/.hermes/config.yaml and add hermes-gemini-web-search to your enabled plugins:

plugins:
  enabled:
    - hermes-gemini-web-search

If you already have other plugins enabled, just add this one to the list. If you have never enabled a plugin before, the plugins section might not exist yet — create it at the top level of the file and add both keys exactly as shown.

Step 3 — Tell Hermes to use it

In the same config.yaml file, under the web section, set the backend:

web:
  backend: gemini

The full config.yaml will look something like this (your file may have other sections — that's fine):

plugins:
  enabled:
    - hermes-gemini-web-search

web:
  backend: gemini

Step 4 — Restart Hermes

Quit and restart your Hermes agent. On the next question that needs web access, the agent will use Gemini.

Verifying it works

Ask your agent something that requires live web access:

> what is the latest stable version of Python?

> who won the most recent Formula 1 race?

> summarize the top story on Hacker News today

If the agent returns current, factual answers, the plugin is working.

You can also check with the Hermes tools picker:

hermes tools

Navigate to Web Search — you should see "Gemini Google Search Grounding" listed with a green checkmark and "free tier available" badge.

How it works

When your agent calls web_search("some query"), the plugin sends the query to Gemini's API with a google_search grounding tool enabled. Gemini searches the live web, retrieves relevant pages, and returns:

• A grounded answer — Gemini's summary of what it found, backed by the search results
• Supporting sources — links to the actual pages so the agent (and you) can verify claims

When your agent calls web_extract(url), the plugin asks Gemini to fetch and summarize the full page content at that URL.

Under the hood, this uses the official google-genai Python SDK. The SDK is installed automatically as a dependency — you never need to think about it.

Advanced configuration

Choosing a model

The default model is gemini-3.1-flash-lite — fast, cheap, and well-suited to search grounding. You can override it in config.yaml:

web:
  backend: gemini
  gemini_model: gemini-2.5-flash

Any model that supports the google_search grounding tool will work. Faster models keep agent response times low. Larger models may produce richer summaries but cost more and take longer.

Using a Google API key instead of a Gemini key

If you use Google Cloud and already have a GOOGLE_API_KEY set, the plugin picks it up automatically:

# ~/.hermes/.env
GOOGLE_API_KEY=AIza...your-google-cloud-key

No extra configuration needed.

Per-capability routing

You can use Gemini for search only (or extract only) while routing the other capability to a different provider:

web:
  search_backend: gemini       # Gemini handles web_search
  extract_backend: firecrawl   # Firecrawl handles web_extract

Configuring via hermes tools

If you prefer the interactive terminal UI:

hermes tools

Navigate to Web Search, select Gemini Google Search Grounding, and follow the prompts. The picker will ask for your API key and set everything up for you.

Troubleshooting

"GEMINI_API_KEY environment variable not set"

The plugin can't find your key. Check that:

• ~/.hermes/.env exists and has a line starting with GEMINI_API_KEY= or GOOGLE_API_KEY=
• There are no extra spaces or quotes around the value
• You restarted Hermes after adding the key

"hermes-gemini-web-search is not enabled"

Hermes found the plugin but hasn't been told to activate it. Check that ~/.hermes/config.yaml contains:

plugins:
  enabled:
    - hermes-gemini-web-search

"Google GenAI SDK not installed"

Run pip install google-genai inside your Hermes environment, then restart.

"Gemini search failed" with a permission error

Your API key may not have the Gemini API enabled. Visit Google AI Studio, select your key, and verify the Gemini API is toggled on. If you are using a Google Cloud key, enable the Gemini API in the Cloud Console.

The agent is not using the plugin

Make sure you restarted Hermes after making the configuration changes. Plugin discovery happens at startup.

Development

git clone https://github.com/your-username/hermes-gemini-web-search.git
cd hermes-gemini-web-search
pip install -e .
pytest

Tests use mocks so no API key or network access is needed to run the suite.