Tavily Search

AI-optimized web search using Tavily API — returns clean, relevant snippets designed for AI agents.

Setup

export TAVILY_API_KEY="your-key-here"

Get API key from: https://tavily.com (free tier available)

Scripts

Located at ~/.hermes/skills/research/tavily-search/scripts/

Search

node ~/.hermes/skills/research/tavily-search/scripts/search.mjs "query"
node ~/.hermes/skills/research/tavily-search/scripts/search.mjs "query" -n 10
node ~/.hermes/skills/research/tavily-search/scripts/search.mjs "query" --deep
node ~/.hermes/skills/research/tavily-search/scripts/search.mjs "query" --topic news
node ~/.hermes/skills/research/tavily-search/scripts/search.mjs "query" --topic news --days 3

Extract content from URL

node ~/.hermes/skills/research/tavily-search/scripts/extract.mjs "https://example.com/article"

Options

• -n <count>: Number of results (default: 5, max: 20)
• --deep: Advanced search for deeper research (slower, more comprehensive)
• --topic <topic>: general (default) or news
• --days <n>: For news topic, limit to last n days

Direct API Usage (no scripts needed)

import os, requests

def tavily_search(query, max_results=5, search_depth="basic"):
    resp = requests.post("https://api.tavily.com/search",
        json={
            "api_key": os.environ["TAVILY_API_KEY"],
            "query": query,
            "max_results": max_results,
            "search_depth": search_depth  # "basic" or "advanced"
        }
    )
    return resp.json()

When to Prefer Tavily Over SearXNG

• Tavily results are pre-cleaned for AI consumption
• Better for research queries requiring comprehension
• --deep mode does multi-step search + synthesis
• News topic search is curated for current events

Pitfalls

• ⚠️ Requires TAVILY_API_KEY — NOT currently set
• Deep search is noticeably slower but much more thorough
• Free tier has rate limits — check https://tavily.com/pricing

Verification

# Confirm API key is set
echo $TAVILY_API_KEY
# Run a basic search and expect JSON results
node ~/.hermes/skills/research/tavily-search/scripts/search.mjs "test query" -n 2
# Extract a known URL
node ~/.hermes/skills/research/tavily-search/scripts/extract.mjs "https://example.com"