Hermes TinyFish Web Search Plugin

🇮🇩 Bahasa Indonesia | 🇨🇳 中文

A Hermes Agent plugin for TinyFish's native web search, fetch, agent & browser API.

Features

• Native TinyFish API — Direct connection, no middleman
• Free Web Search — $0/call, 30 req/min
• Free Web Fetch — $0/call, 150 URLs/min
• Structured Results — Titles, URLs, descriptions, positions
• Clean Markdown Extraction — Renders JS-heavy pages in real browser
• Agent API — Natural-language goals for website automation
• Browser API — Remote browser sessions via CDP WebSocket

Pricing

| API | Price | Limits | |-----|-------|--------| | Search | $0/call | 30 req/min | | Fetch | $0/call | 150 URLs/min | | Agent | $0.016/step | 2 concurrent runs | | Browser | $0.002/min | 5 concurrent sessions |

Prerequisites

1. TinyFish API Key — Get one at https://agent.tinyfish.ai/api-keys
2. Hermes Agent — Install via curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Installation

Option 1: npm (Recommended)

npm install -g hermes-tinyfish-websearch

Option 2: Manual

git clone https://github.com/ashafizullah/hermes-tinyfish-websearch.git
cp -r hermes-tinyfish-websearch ~/.hermes/plugins/web/tinyfish

Option 3: Direct Download

mkdir -p ~/.hermes/plugins/web/tinyfish
curl -sL https://raw.githubusercontent.com/ashafizullah/hermes-tinyfish-websearch/main/provider.py -o ~/.hermes/plugins/web/tinyfish/provider.py
curl -sL https://raw.githubusercontent.com/ashafizullah/hermes-tinyfish-websearch/main/__init__.py -o ~/.hermes/plugins/web/tinyfish/__init__.py
curl -sL https://raw.githubusercontent.com/ashafizullah/hermes-tinyfish-websearch/main/plugin.yaml -o ~/.hermes/plugins/web/tinyfish/plugin.yaml

Configuration

1. Add API Key

echo "TINYFISH_API_KEY=sk-tinyfish-..." >> ~/.hermes/.env

2. Update config.yaml

hermes config set plugins.enabled '["web/tinyfish"]'
hermes config set web.backend tinyfish
hermes config set web.search_backend tinyfish
hermes config set web.extract_backend tinyfish

Or manually:

plugins:
  enabled:
    - web/tinyfish

web:
  backend: tinyfish
  search_backend: tinyfish
  extract_backend: tinyfish
  tinyfish:
    timeout: 60
    max_fetch_urls: 5
    agent_max_steps: 50
    agent_max_duration: 300

3. Restart Gateway

hermes gateway restart

TinyFish MCP Server

TinyFish also provides an official MCP server for AI assistants (Claude Code, Codex, OpenCode, ChatGPT). Uses OAuth authentication, no API key management needed.

Endpoint: https://agent.tinyfish.ai/mcp

Setup:

• Codex: codex mcp add tinyfish --url https://agent.tinyfish.ai/mcp
• Claude Code: npx -y install-mcp@latest https://agent.tinyfish.ai/mcp --client claude-code
• OpenCode: opencode mcp add tinyfish --url https://agent.tinyfish.ai/mcp

The MCP server supports all TinyFish tools: Agent, Search, Fetch, Browser. Use this plugin for native Hermes web_search/web_extract integration, or use the MCP server for direct AI assistant connections.

API Reference

Search

GET https://api.search.tinyfish.ai?query=YOUR_QUERY&limit=5
Header: X-API-Key: your_api_key

Fetch

POST https://api.fetch.tinyfish.ai
Header: X-API-Key: your_api_key
Body: {"urls": ["https://example.com"]}

Agent

POST https://agent.tinyfish.ai/v1/automation/run
Header: X-API-Key: your_api_key
Body: {"url": "https://example.com", "goal": "Extract the title", "agent_config": {"max_steps": 10, "max_duration_seconds": 30}}

Browser

POST https://api.browser.tinyfish.ai
Header: X-API-Key: your_api_key
Body: {"url": "https://example.com", "timeout_seconds": 300}

Response includes session_id, cdp_url, base_url — connect via Playwright's connect_over_cdp(cdp_url).

Provider Configuration

Under web.tinyfish in config.yaml:

| Key | Default | Description | |-----|---------|-------------| | timeout | 60 | Request timeout in seconds | | max_fetch_urls | 5 | Max URLs per extract (1-10) | | agent_max_steps | 50 | Max agent steps (1-500) | | agent_max_duration | 300 | Max agent duration in seconds |

Privacy

TinyFish has a published privacy policy: https://www.tinyfish.ai/privacy-policy

This plugin connects directly to TinyFish's API — no middleman, no proxy. Your API key is sent only via HTTPS X-API-Key header to TinyFish domains.

Credits

• TinyFish — Free web search & fetch API
• Hermes Agent — AI agent framework

License

MIT © Adam Suchi Hafizullah