Fix Hermes v0.12 search API fallback issues by adding a secondary search provider that activates when the primary provider fails. Hermes v0.12 agents commonly encounter search grounding failures when the default search tool times out, returns empty results, or hits rate limits during high-throughput operation. Adding a fallback search provider with automatic retry logic ensures the agent always has access to search data, preventing the cascading hallucination that occurs when grounding data is missing.
Prerequisites
- Python 3.8+ installed
- requests library installed
- A Scavio API key from scavio.dev
- A Hermes v0.12 agent with search grounding
Walkthrough
Step 1: Diagnose the failure mode
Identify which search failures your Hermes agent encounters most frequently.
Python
import os, requests, time
API_KEY = os.environ['SCAVIO_API_KEY']
# Common Hermes v0.12 search failure modes:
FAILURE_MODES = {
'timeout': 'Search request took >10s, agent proceeded without data',
'empty_results': 'Search returned 0 results, agent hallucinated answer',
'rate_limit': 'HTTP 429 from primary provider, no retry attempted',
'malformed_json': 'Response was not valid JSON, parser crashed',
}
def diagnose_search(query: str) -> dict:
"""Test search reliability and measure response characteristics."""
start = time.time()
try:
resp = requests.post('https://api.scavio.dev/api/v1/search',
headers={'x-api-key': API_KEY},
json={'platform': 'google', 'query': query}, timeout=15)
elapsed = time.time() - start
data = resp.json()
results = data.get('organic_results', [])
return {
'status': resp.status_code,
'latency_ms': round(elapsed * 1000),
'result_count': len(results),
'has_data': len(results) > 0,
'error': None,
}
except requests.Timeout:
return {'status': 0, 'latency_ms': 15000, 'result_count': 0, 'has_data': False, 'error': 'timeout'}
except Exception as e:
return {'status': 0, 'latency_ms': 0, 'result_count': 0, 'has_data': False, 'error': str(e)}
diag = diagnose_search('latest python release')
print(f"Status: {diag['status']}, Latency: {diag['latency_ms']}ms, Results: {diag['result_count']}")Step 2: Build fallback search function
Create a search function with automatic retry and fallback logic.
Python
def search_with_fallback(query: str, max_retries: int = 2) -> dict:
"""Search with retry logic. Returns results or empty dict on total failure."""
for attempt in range(max_retries + 1):
try:
resp = requests.post('https://api.scavio.dev/api/v1/search',
headers={'x-api-key': API_KEY},
json={'platform': 'google', 'query': query},
timeout=10 + (attempt * 5)) # Increasing timeout per retry
if resp.status_code == 429:
wait = 2 ** attempt
print(f'Rate limited, waiting {wait}s...')
time.sleep(wait)
continue
resp.raise_for_status()
data = resp.json()
results = data.get('organic_results', [])
if results:
return {'results': results, 'source': 'scavio', 'attempt': attempt + 1}
except requests.Timeout:
print(f'Timeout on attempt {attempt + 1}')
except requests.RequestException as e:
print(f'Error on attempt {attempt + 1}: {e}')
return {'results': [], 'source': 'none', 'attempt': max_retries + 1}
result = search_with_fallback('latest python release')
print(f"Source: {result['source']}, Attempt: {result['attempt']}, Results: {len(result['results'])}")Step 3: Integrate with Hermes agent
Replace the default search tool in your Hermes agent with the fallback-enabled version.
Python
class HermesSearchTool:
"""Fallback-enabled search tool for Hermes v0.12 agents."""
def __init__(self, api_key: str):
self.api_key = api_key
self.stats = {'calls': 0, 'retries': 0, 'failures': 0}
def search(self, query: str) -> list:
self.stats['calls'] += 1
result = search_with_fallback(query)
if result['attempt'] > 1:
self.stats['retries'] += 1
if not result['results']:
self.stats['failures'] += 1
return [{
'title': r.get('title', ''),
'snippet': r.get('snippet', ''),
'url': r.get('link', ''),
} for r in result['results'][:5]]
def get_stats(self) -> dict:
return self.stats
tool = HermesSearchTool(API_KEY)
results = tool.search('hermes agent grounding')
print(f'Results: {len(results)}')
print(f'Stats: {tool.get_stats()}')Step 4: Add health check endpoint
Create a health check that monitors search availability and alerts on degradation.
Python
def health_check() -> dict:
"""Quick health check for search API availability."""
test_queries = ['test', 'hello world', 'python']
healthy = 0
total_latency = 0
for q in test_queries:
diag = diagnose_search(q)
if diag['has_data']:
healthy += 1
total_latency += diag['latency_ms']
avg_latency = total_latency // len(test_queries)
status = {
'healthy': healthy == len(test_queries),
'success_rate': f'{healthy}/{len(test_queries)}',
'avg_latency_ms': avg_latency,
'status': 'ok' if healthy == len(test_queries) else 'degraded' if healthy > 0 else 'down',
}
print(f"Search health: {status['status']} ({status['success_rate']} ok, {status['avg_latency_ms']}ms avg)")
return status
health_check()Python Example
Python
import requests, os, time
H = {'x-api-key': os.environ['SCAVIO_API_KEY']}
def search_safe(query, retries=2):
for i in range(retries + 1):
try:
r = requests.post('https://api.scavio.dev/api/v1/search', headers=H,
json={'platform': 'google', 'query': query}, timeout=10 + i*5)
results = r.json().get('organic_results', [])
if results: return results[:5]
except: pass
time.sleep(2 ** i)
return []
print(search_safe('test query'))JavaScript Example
JavaScript
const H = {'x-api-key': process.env.SCAVIO_API_KEY, 'Content-Type': 'application/json'};
async function searchSafe(query, retries = 2) {
for (let i = 0; i <= retries; i++) {
try {
const r = await fetch('https://api.scavio.dev/api/v1/search', {
method: 'POST', headers: H,
body: JSON.stringify({platform: 'google', query})
});
const results = (await r.json()).organic_results || [];
if (results.length) return results.slice(0, 5);
} catch(e) {}
await new Promise(r => setTimeout(r, 1000 * Math.pow(2, i)));
}
return [];
}
searchSafe('test query').then(console.log);Expected Output
JSON
A Hermes v0.12 agent with reliable search grounding that retries on failure, handles rate limits gracefully, and includes health monitoring for proactive issue detection.