Hermes TinyFish Web Search

Give your Hermes agent live access to the web — powered by the TinyFish API.

When your agent needs to look something up, this plugin answers with grounded, sourced results instead of stale training data. It covers the full TinyFish API surface: search, content extraction, browser sessions, and agent automation.

Why use this plugin?

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

Search is free. TinyFish Search API does not consume credits. Fetch API is also credit-free. You only pay for browser and agent automation runs.

Complete API coverage. This plugin exposes all four TinyFish APIs as discrete tools: Search for ranked results, Fetch for page extraction, Browser for remote CDP sessions, and Agent for goal-based automation.

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 TinyFish API key (free tier available)

Getting a TinyFish API key

1. Go to agent.tinyfish.ai/api-keys in your browser
2. Sign up for a free account or log in if you already have one
3. Create an API key and copy it

Installation

One command

From inside your Hermes environment:

pip install hermes-tinyfish-web-search

Or from source

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

Configuration

Step 1 — Add your API key

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

TINYFISH_API_KEY=your-api-key-here

Step 2 — Enable the plugin

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

plugins:
  enabled:
    - hermes-tinyfish-web-search

Step 3 — Tell Hermes to use it

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

web:
  backend: tinyfish

The full config.yaml will look something like this:

plugins:
  enabled:
    - hermes-tinyfish-web-search

web:
  backend: tinyfish

Step 4 — Restart Hermes

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

Available tools

The plugin registers six tools under the tinyfish toolset:

Tool	API	Description
web_search_tinyfish	Search	Web search with geo-targeting, date filters, news, and academics
web_extract_tinyfish	Fetch	Extract clean page content from a single URL
web_extract_batch_tinyfish	Fetch	Extract content from up to 10 URLs in one request
browser_create_session_tinyfish	Browser	Create a remote browser session (returns CDP WebSocket URL)
browser_terminate_session_tinyfish	Browser	Terminate a browser session by session_id
agent_automation_tinyfish	Agent	Run goal-based browser automation with natural language

Search features

• Geo-targeted results (location, language)
• Date filtering (recency_minutes, after_date, before_date)
• Domain type: web (default), news, research_paper
• Domain filtering (include_domains, exclude_domains)
• Academic search with pub_year_min/pub_year_max

Fetch features

• Output formats: markdown (default), html, json
• CSS selector scoping (include_selectors, exclude_selectors)
• Cache control (ttl)
• Extract links and image links

Browser features

• Create remote browser sessions with CDP WebSocket URLs
• Compatible with Playwright, Puppeteer, and any CDP client
• Configurable inactivity timeout

Agent features

• Goal-based automation with natural language instructions
• Structured output with output_schema
• Browser profiles (lite, stealth)
• Step and duration limits

How it works

When your agent calls web_search("some query"), the plugin sends the query to the TinyFish Search API (GET https://api.search.tinyfish.ai) and returns ranked results with titles, snippets, and URLs.

When your agent calls web_extract(url), the plugin sends the URL to the TinyFish Fetch API (POST https://api.fetch.tinyfish.ai) for full-page content extraction in the requested format.

Under the hood, this uses httpx for HTTP requests. It is installed automatically as a dependency.

Per-capability routing

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

web:
  search_backend: tinyfish     # TinyFish handles web_search
  extract_backend: keiroslabs   # KeiroLabs handles web_extract

Troubleshooting

"TINYFISH_API_KEY environment variable not set"

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

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

"Invalid TINYFISH_API_KEY" or "access denied"

Your API key may be incorrect or expired. Visit agent.tinyfish.ai/api-keys to verify your key is still active. Generate a new key if needed.

"TinyFish API: payment required"

Your subscription does not include access to the requested API (Browser or Agent). Visit agent.tinyfish.ai to upgrade your plan.

"Failed to connect to TinyFish API"

Check:

• Your internet connection is working
• You can reach https://api.search.tinyfish.ai in a browser or with curl
• No firewall or VPN is blocking outbound HTTPS on port 443

Development

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

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