hermesbrowsersearch-api

Hermes Agent: Browser Automation vs Search API

Use browser automation for behind-login pages. Use search API for everything else. Most Hermes tasks should default to API search -- faster, cheaper, more reliable.

May 21, 2026

8 min

Hermes Agent supports both browser automation (Playwright-based) and search API tools. Use browser automation for behind-login pages, form submissions, and interactive workflows. Use search APIs for everything else -- they are faster, cheaper, and do not trigger bot detection. Most Hermes users should default to API search and add browser only when the target requires JavaScript interaction.

When to use browser automation

Target is behind authentication (login required)
Need to fill forms, click buttons, or navigate multi-step flows
Extracting data from JavaScript-rendered SPAs with no API
Screenshot capture for visual verification

When to use search API

Finding information across search engines (Google, YouTube, Reddit)
Product research (Amazon, Walmart, TikTok Shop)
Getting structured data without parsing HTML
Any query where you need JSON, not a rendered page

Add search API to Hermes

Python

# hermes_config.py - Add Scavio as a search tool
import requests

def web_search(query: str, num_results: int = 5) -> list:
    """Search tool for Hermes Agent."""
    resp = requests.post(
        "https://api.scavio.dev/api/v1/search",
        headers={"x-api-key": "YOUR_KEY"},
        json={"query": query, "num_results": num_results}
    )
    data = resp.json()
    return [
        {
            "title": r["title"],
            "url": r["url"],
            "snippet": r.get("snippet", "")
        }
        for r in data.get("organic_results", [])
    ]

def youtube_search(query: str) -> list:
    """YouTube search tool for Hermes Agent."""
    resp = requests.post(
        "https://api.scavio.dev/api/v1/search",
        headers={"x-api-key": "YOUR_KEY"},
        json={"query": query, "platform": "youtube", "num_results": 5}
    )
    data = resp.json()
    return data.get("video_results", [])

# Register tools with Hermes
TOOLS = [web_search, youtube_search]

Cost comparison: browser vs API

Text

Approach       | Time/query | Cost/query  | Reliability
Browser        | 3-10 sec   | $0.01-0.05  | 70-85% (bot detection)
Search API     | 0.5-2 sec  | $0.005      | 99%+
SearXNG        | 1-3 sec    | Free        | 60-80% (gets blocked)

Hybrid pattern for Hermes

JavaScript

// Use API first, fall back to browser only when needed
async function smartSearch(query, needsBrowser = false) {
  if (!needsBrowser) {
    // Default: use search API (fast, cheap, reliable)
    const resp = await fetch("https://api.scavio.dev/api/v1/search", {
      method: "POST",
      headers: {
        "x-api-key": process.env.SCAVIO_KEY,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({ query, num_results: 5 })
    });
    return resp.json();
  }

  // Fallback: browser automation for auth-gated content
  // This is where Hermes Playwright integration kicks in
  console.log("Using browser automation for:", query);
  // ... Playwright code here
}

// 95% of agent tasks use API, 5% need browser
const results = await smartSearch("best database for startups");

Decision framework

Can you get the data from a search query? Use API.
Is the target a public website with structured content? Use API.
Does the target require login, form fill, or JavaScript interaction? Use browser.
Is reliability critical? Use API (browser automation has ~15-30% failure rate).