Summary

Add Brave Search API as a first-class web search backend in hermes-agent, alongside existing providers (Firecrawl, Parallel, Tavily, Exa).

Motivation

Brave Search is one of the most accessible and cost-effective search APIs available:

• Generous free tier with monthly trial credits
• Well-documented REST API with structured JSON responses
• Supports web search, query autosuggest, and AI-grounded answers with citations
• Privacy-focused — no tracking, no user profiling
• Already widely adopted (used by OmniRoute as brave-search provider)

Proposed Integration

1. New tool file: tools/brave_search_tool.py

Three tools registered via the standard registry.register() pattern:

brave_search — Web Search

• Endpoint: GET https://api.search.brave.com/res/v1/web/search
• Auth: X-Subscription-Token header with BRAVE_API_KEY or BRAVE_SEARCH_API_KEY
• Parameters:
  • query (required) — search query, supports operators: site:, "exact phrase", -exclude
  • count (1-20, default 10)
  • country (2-letter code, default us)
  • freshness — pd (24h), pw (7d), pm (31d), py (1y)
  • extra_snippets (bool) — up to 5 extra excerpts per result
  • summary (bool) — fetch Brave AI summarizer result

Response format (standardized):

{
  "query": "...",
  "results": [
    {
      "title": "...",
      "url": "https://...",
      "description": "...",
      "extra_snippets": ["..."]
    }
  ],
  "ai_summary": "..."
}

brave_suggest — Query Autosuggest

• Endpoint: GET https://api.search.brave.com/res/v1/suggest/search
• Parameters: query, count (1-10), country, rich (metadata)
• Response: {"query": "...", "suggestions": ["..."]}

brave_answers — AI-Grounded Answers

• Endpoint: POST https://api.search.brave.com/res/v1/chat/completions
• Auth: BRAVE_ANSWERS_API_KEY (may differ from search key)
• Body: OpenAI-compatible chat format with model: "brave"
• Extra params: enable_citations, enable_research (multi-search deep mode)
• Parses <citation>...</citation> tags to extract sources

Response format:

{
  "answer": "...",
  "sources": [
    {"url": "...", "title": "...", "snippet": "..."}
  ],
  "tokens": 123
}

2. Backend integration in web_tools.py

Add "brave" to:

• _get_backend() — valid configured backend name
• _is_backend_available() — check for BRAVE_API_KEY or BRAVE_SEARCH_API_KEY
• backend_candidates fallback list (priority: after firecrawl, before parallel)
• _web_requires_env() — include BRAVE_API_KEY, BRAVE_SEARCH_API_KEY

3. Toolset updates in toolsets.py

Add brave_search and brave_answers to:

• "web" toolset: ["web_search", "web_extract", "brave_search", "brave_answers"]
• "search" toolset: ["web_search", "brave_search", "brave_answers"]

4. Config updates in hermes_cli/config.py

Add to OPTIONAL_ENV_VARS:

"BRAVE_API_KEY": {
    "description": "Brave Search API key (web search)",
    "prompt": "Brave Search API Key",
    "url": "https://api-dashboard.search.brave.com",
    "category": "tool",
}
"BRAVE_SEARCH_API_KEY": {
    "description": "Brave Search API key (explicit, overrides BRAVE_API_KEY)",
    "prompt": "Brave Search API Key",
    "url": "https://api-dashboard.search.brave.com",
    "category": "tool",
}
"BRAVE_ANSWERS_API_KEY": {
    "description": "Brave AI Answers API key (requires paid plan)",
    "prompt": "Brave Answers API Key",
    "url": "https://api-dashboard.search.brave.com",
    "category": "tool",
}

Add "brave" to the web backend selector in hermes tools setup.

5. Tool discovery in model_tools.py

Add "tools.brave_search_tool" to the _modules list in _discover_tools().

Existing Web Search Providers (for reference)

Brave complements existing providers by offering autosuggest and AI-grounded answers — features none of the current backends provide natively.

Pricing Reference

• Brave API: credit-based, monthly trial credits available
• Dashboard: https://api-dashboard.search.brave.com
• Docs: https://brave.com/search/api/

Dependencies

Zero additional dependencies — uses only httpx (already a hermes-agent dependency).

Reference Implementation

Based on Brave API Search skill (MIT-0 license) — adapted from Node.js scripts to native Python.

Testing

# Basic search
brave_search(query="Python machine learning", count=5, country="br")

# AI answers (requires paid plan)
brave_answers(query="How does React Server Components work?")

# Autosuggest
brave_suggest(query="pyt", count=5)