All plugins

serpapi

SerpApi web, Maps, News, Shopping, Hotels, Flights, Travel Explore, and page extraction for Hermes Agent. Scrape pages, map URLs, or crawl sites.

serpapi3Webv1.2.0Updated 8 days ago

SerpApi for Hermes Agent

PyPI version
CI
Python versions
License: MIT

Use SerpApi in Hermes Agent for web search, Maps, News, Shopping, Hotels, Flights, Travel Explore, and page extraction.

Queries and requested URLs are sent to SerpApi using your API key. SerpApi fetches the requested pages; the plugin adds no telemetry.

The plugin provides:

  • Hermes's built-in web_search uses the fast Google Light engine.
  • Dedicated Maps, News, Shopping, Hotels, Flights, and Travel Explore tools let Hermes choose the right SerpApi engine. They return Markdown by default, with JSON available.
  • web_extract reads page content through SerpApi. serpapi_extract adds scraping, URL mapping, and crawling, with compact content or full JSON through compact_mode: false.

Ask Hermes to install it

You can let Hermes install and configure the plugin for you. Paste the message below into a Hermes chat, then approve the install or terminal commands if Hermes prompts you:

Install and configure the SerpApi plugin from its official GitHub repository:

hermes plugins install serpapi/serpapi-hermes-plugin --enable

Request my approval for install or terminal commands whenever required; do not
bypass approvals. Follow Hermes's prompts to install Python dependencies and
enable the plugin named serpapi.

If Hermes asks whether to allow this plugin to replace built-in tools, answer
no; serpapi-hermes-plugin does not need tool-override access.

Use my existing SERPAPI_API_KEY if configured. Otherwise, ask me for my SerpApi
Private API Key when installation or setup requests it. I can copy it from
https://serpapi.com/dashboard. Save it through Hermes's configuration in
~/.hermes/.env without printing, logging, or committing it.

Configure SerpApi as the Hermes web search and extract backend, tell me whether Hermes must be restarted, and verify that web search, page extraction, Maps, News, Shopping, Hotels, Flights, and Travel Explore tools are available. Use this key for future SerpApi requests and never expose it in output.

Install

You need Hermes Agent 0.21.6 or later and a SerpApi account. Choose one installation method below. Both register the plugin as serpapi and provide the same search and extraction tools.

From GitHub (recommended)

Use Hermes's plugin installer:

hermes plugins install serpapi/serpapi-hermes-plugin --enable

Follow the prompts for Python dependencies, enablement, and your SerpApi API key. Use a current Hermes version with plugin dependency management; older installers may clone the plugin without installing its dependencies.

To update a Git installation later:

hermes plugins update serpapi

GitHub installs follow the repository; catalog installs receive maintainer-reviewed releases through the same update command.

From PyPI

For Hermes installations whose Python environment you manage yourself, install the published package into the interpreter that runs Hermes:

uv pip install --python /path/to/hermes/python serpapi-hermes-plugin
hermes plugins enable serpapi

If your Hermes installation uses ~/.hermes/hermes-agent/venv, the install command is:

uv pip install --python ~/.hermes/hermes-agent/venv/bin/python serpapi-hermes-plugin

The explicit --python selects Hermes's environment without activating it. If that environment already has pip and is activated, python -m pip install serpapi-hermes-plugin is equivalent. Use the GitHub option for current Hermes-managed installations, as described in Hermes's pip distribution guidance.

Restart any running Hermes session after installation.

Get your SerpApi API key

  1. Create a SerpApi account, or sign in to
    your existing account.
  2. Open the SerpApi dashboard.
  3. Find your Private API Key in the dashboard and copy it.

One API key powers every engine in this plugin. Keep it private and never add it
to source control.

Connect the API key to Hermes

If the plugin is not enabled yet, enable it:

hermes plugins enable serpapi

If prompted about permission to replace built-in tools, answer no. This
plugin adds new tools and a web-search provider; it does not replace built-in
tool handlers.

Open Hermes's interactive tool configuration:

hermes tools

In the Web Search & Extract section:

  1. Select SerpApi.
  2. Paste the Private API Key copied from your SerpApi dashboard.
  3. Confirm the selection.

Hermes saves the key as SERPAPI_API_KEY in its environment configuration and selects SerpApi for future web_search calls. Also select SerpApi as the extract backend, or set web.extract_backend: serpapi as shown below. Restart Hermes if a session was already running.

Manual API-key setup

Instead of using hermes tools, add the key to ~/.hermes/.env:

SERPAPI_API_KEY=your_private_api_key

Then configure ~/.hermes/config.yaml:

plugins:
  enabled:
    - serpapi

web:
  search_backend: serpapi
  extract_backend: serpapi

You may also export SERPAPI_API_KEY in the environment that starts Hermes.
The environment variable takes precedence over the value in ~/.hermes/.env.

Search and extraction capabilities

Ask Hermes what you need; it chooses the tool and supplies the parameters. Direct search tools return Markdown by default and support JSON when structured data is needed.

What you ask forHermes toolSerpApi engine
General web researchweb_searchgoogle_light
Read page contentweb_extractextract
Scrape pages, map URLs, or crawl a siteserpapi_extractextract
Places and local businessesserpapi_maps_searchgoogle_maps
Current and recent newsserpapi_news_searchgoogle_news_light
Products, prices, and merchantsserpapi_shopping_searchgoogle_shopping_light
Hotels and vacation rentalsserpapi_hotels_searchgoogle_hotels
Fixed-route flight faresserpapi_flights_searchgoogle_flights
Flexible destinations and datesserpapi_travel_explore_searchgoogle_travel_explore

Example prompts:

  • "Search the web for the latest Python 3.15 release notes."
  • "Read https://www.python.org/about/ and summarize it."
  • "Extract the product details and prices from this page."
  • "Map this website and read the three pages most relevant to my question."
  • "Find highly rated coffee shops near Times Square."
  • "Show me recent news about reusable rockets."
  • "Find well-reviewed laptops under $1,200 with free shipping."
  • "Find four-star hotels in Kyoto for a five-night stay next month."
  • "Compare nonstop business-class flights from JFK to LAX next month."
  • "Where can I go from Bengaluru for a one-week beach trip in December?"

Page extraction

With web.extract_backend: serpapi, Hermes uses SerpApi to read pages. The serpapi_extract tool also lets the agent choose between:

  • scrape: Read one page (default).
  • map: Discover a website's URLs.
  • crawl: Follow links and read multiple pages.

Results are compact by default, with full JSON available through compact_mode: false. Search URLs return results from their dedicated engines. The agent can limit crawl size and depth, include sitemaps or subdomains, and filter page elements.

Pages are fetched without running JavaScript. Crawling uses one search credit per successfully extracted page. See the Extract API documentation for details.

Contributing

See CONTRIBUTING.md
for development setup, tests, pull request guidelines, and the release process.

License

MIT

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

Developer Mode

Explore built-in Hermes toolsets and actions.

HermesAgent

Developer?

Create a Hermes extension for Desktop or agent workflows.

Developer Section