tinyfish-integration

TinyFish Integration

TinyFish is a web toolkit for AI agents that provides search, fetch, and browser automation capabilities. Search and fetch are free for every account — no credits, no cost.

Available Tools

tinyfish_search

Search the live web and get structured, agent-ready results.

Use cases:

• Current information, news, prices
• Finding URLs before fetching content
• Anything that changes over time

Parameters:

• query (required): Search query string
• location (optional): 2-letter country code (e.g., "US", "FR", "ID")
• language (optional): 2-letter language code (e.g., "en", "fr", "id")
• page (optional): Page number for pagination (default: 0)

Example:

tinyfish_search(query="Hermes Agent AI", location="US", language="en")

Response format:

{
  "results": [
    {
      "title": "Page Title",
      "url": "https://example.com",
      "snippet": "Description text...",
      "site_name": "Example Site"
    }
  ]
}

tinyfish_fetch

Pull the full content of any web page as clean extracted text.

Use cases:

• Reading articles, docs, product pages
• Extracting content without ads/navigation
• Batch processing multiple URLs (max 10)

Parameters:

• urls (required): Single URL or comma-separated list (max 10)

Examples:

# Single URL
tinyfish_fetch(urls="https://example.com")

# Multiple URLs
tinyfish_fetch(urls="https://site1.com, https://site2.com, https://site3.com")

Response format:

{
  "results": [
    {
      "url": "https://example.com",
      "final_url": "https://example.com",
      "title": "Page Title",
      "description": "Meta description",
      "language": "en",
      "text": "# Heading\n\nClean extracted content..."
    }
  ],
  "errors": []
}

Setup

1. Get API Key

Visit https://agent.tinyfish.ai/api-keys to get your API key.

2. Configure Hermes

Add to ~/.hermes/.env:

TINYFISH_API_KEY=sk-tinyfish-YOUR_KEY_HERE

3. Enable Toolset

Add to ~/.hermes/config.yaml:

toolsets:
  - tinyfish

4. Verify Installation

hermes chat -q "Search for 'Hermes Agent' using tinyfish_search"

Tool Implementation

The TinyFish tools are implemented in ~/.hermes/hermes-agent/tools/tinyfish_search.py:

• tinyfish_search: GET request to https://api.search.tinyfish.ai
• tinyfish_fetch: POST request to https://api.fetch.tinyfish.ai with JSON body

Both tools:

• Use X-API-Key header for authentication
• Return JSON responses
• Handle errors gracefully
• Support 60-second timeout for fetch (30s for search)

When to Use Each Tool

| Tool | Use When | |------|----------| | tinyfish_search | You need to find URLs or get current information | | tinyfish_fetch | You already know the URL and need the content | | Agent API | TinyFish should perform multi-step workflows | | Browser API | You need direct browser control from your code |

Supported Content Types (Fetch)

• ✅ HTML pages (clean text extraction)
• ✅ PDF files (text extraction)
• ✅ JSON endpoints (raw JSON)
• ❌ Binary files (images, video) — returns error

Limitations

• Search: No explicit rate limit documented
• Fetch: Max 10 URLs per request
• Timeout: 60 seconds for fetch, 30 seconds for search
• Free tier: Search and fetch are free with no credit cost

Troubleshooting

"TINYFISH_API_KEY environment variable not set"

• Check ~/.hermes/.env has the key
• Restart Hermes after adding the key

"HTTP 401: Unauthorized"

• Verify API key is correct
• Check key hasn't expired at https://agent.tinyfish.ai/api-keys

"HTTP 405: Method Not Allowed"

• This was the old bug — fetch now uses POST correctly
• Update to latest tool version if you see this

Timeout errors

• Fetch has 60s timeout — some pages may be slow
• Try fetching fewer URLs at once
• Check if the target site is accessible

Advanced Usage

Batch Fetch with Error Handling

# Fetch multiple URLs — errors don't affect other URLs
result = tinyfish_fetch(urls="https://site1.com, https://site2.com, https://invalid-url.com")

# Response includes both results and errors
{
  "results": [...],  # Successful fetches
  "errors": [...]    # Failed URLs with error messages
}

Geo-Targeted Search

# Search from specific country
tinyfish_search(query="best pizza", location="IT", language="it")

Pagination

# Get page 2 of results
tinyfish_search(query="AI agents", page=1)

Browser Automation (Advanced)

For sites protected by Cloudflare or requiring JavaScript execution, use the Browser API with CDP websocket automation.

See: references/cloudflare-bypass-pattern.md for complete workflow including:

• Cloudflare Turnstile bypass with retry loop
• CDP websocket automation via Runtime.evaluate
• Token injection via localStorage
• Transactional operation patterns (check → act → verify)

Key pattern:

1. Create browser session → wait for Cloudflare bypass (30 retries, 5s interval)
2. Connect to CDP websocket → inject auth tokens
3. Execute API calls via Runtime.evaluate with fetch()
4. Always cleanup session when done

References

• TinyFish Docs: https://docs.tinyfish.ai/
• API Keys: https://agent.tinyfish.ai/api-keys
• Cookbook: https://github.com/tinyfish-io/tinyfish-cookbook
• Cloudflare Bypass Pattern: references/cloudflare-bypass-pattern.md