TalorData for Hermes Agent

Give Hermes Agent Google web search results backed by the TalorData SERP API.

The plugin integrates with Hermes in two ways:

• Hermes's built-in web_search can use TalorData as its backend (Google engine).
• A dedicated talordata_google_search tool exposes the full Google search parameter set (device, location, language, time range, pagination, etc.).

This release supports the google engine only. bing / yandex / duckduckgo will be added in later versions as needed.

Install

Prerequisites: a working Hermes Agent installation and a valid TalorData SERP API Token.

Install from this repository into the same Python environment as Hermes:

cd <repo root>
uv pip install --python /path/to/hermes/python .

If Hermes was installed with its standard installer (source under ~/.hermes/hermes-agent), use its venv interpreter explicitly:

cd ~/.hermes/hermes-agent
uv pip install --python venv/bin/python <repo root>

Restart any running Hermes session after installation, then enable the plugin:

hermes plugins enable talordata

If asked whether to allow the plugin 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.

Get an API Token

1. Sign in to the TalorData dashboard and open the SERP API API Token page.
2. Create or copy your API Token. Note that our authentication credential is called an API Token, not an api_key.

Connect the token to Hermes

Open Hermes's interactive tool configuration:

hermes tools

In the Web Search & Extract section:

1. Select TalorData.
2. Paste the API Token.
3. Confirm the selection.

Hermes saves the token as TALOR_API_TOKEN in its environment configuration and web_search will use TalorData from then on. Restart Hermes if a session was already running.

Manual setup

Add the token to Hermes's environment file (default ~/.hermes/.env):

TALOR_API_TOKEN=your_api_token

Then configure ~/.hermes/config.yaml (or use hermes config set):

plugins:
  enabled:
    - talordata

web:
  search_backend: talordata

You may also export TALOR_API_TOKEN in the environment that starts Hermes. The environment variable takes precedence over the value in .env.

Search capabilities

What you ask for	Hermes tool	TalorData engine
General web research	web_search	google
Google search with advanced options	talordata_google_search	google

Example prompts:

• "Search the web for the latest Python 3.14 release notes."
• "Search Google for Node.js 22 release notes from the past week."

talordata_google_search supports the following parameters (aligned with configs/serp_schemas/engines/google.yaml in the TalorData backend):

• query (required), device (desktop/mobile/tablet)
• location (country/region), google_domain, gl, hl
• tbm (images/shops/news/videos/local/patents search types)
• tbs (past hour / day / week / month / year)
• safe, nfpr, filter
• start, num (1-100, upstream result count), render_js, ai_overview, no_cache

Request & response notes

• Request: POST https://serpapi.talordata.net/serp/v1/request with Authorization: Bearer <API Token> and Content-Type: application/x-www-form-urlencoded.
• Output format (json parameter). Valid values, passed through as-is; 1 is the default:
  • 1 — JSON only (default)
  • 2 — JSON + HTML
  • 3 — HTML
  • 6 — Markdown only
  • 7 — Markdown + HTML
• Responses are SerpApi-compatible: web results live under organic_results with title / link / snippet per item. Some responses wrap the payload in result / data / response keys; the plugin unwraps them automatically.
• Business errors look like {"code": 401, "data": "..."}; any non-zero code is treated as a failure.
• The upstream does not support exit IPs in mainland China (it returns Not supported for use in mainland China); use an overseas node to call it.

Development

# Install development dependencies
uv sync

# Run tests
pytest

# Lint
ruff check .

License

MIT