Hermes v0.13.0 se envió con una herramienta de búsqueda web defectuosa que devuelve resultados vacíos o agota el tiempo de espera para muchas consultas. El problema surge porque su motor de búsqueda predeterminado tiene una velocidad limitada y no es confiable. En lugar de esperar un parche, puede cambiar un backend de API de búsqueda que funcione en minutos. Este tutorial muestra cómo reemplazar la herramienta de búsqueda Hermes con la API Scavio, que devuelve datos SERP estructurados de manera confiable a $0,005 por consulta. La solución requiere cambiar sólo la función de búsqueda, no se necesitan otros cambios en el código del agente.
Requisitos previos
- Hermes v0.13.x instalado
- Python 3.9+ instalado
- solicita biblioteca instalada
- Una clave API de Scavio de scavio.dev
Guia paso a paso
Paso 1: Diagnosticar la herramienta de búsqueda rota
Primero, confirme el problema de búsqueda ejecutando una consulta de prueba a través de Hermes y verificando el resultado de la herramienta. Los modos de error típicos son resultados vacíos, errores de tiempo de espera o JSON con formato incorrecto.
# Test the current Hermes search tool:
# In your Hermes agent, run a query that requires search:
# "What is the current price of Bitcoin?"
#
# Common error outputs:
# - {"results": []} (empty results)
# - TimeoutError: Search request timed out after 30s
# - JSONDecodeError: Expecting value (malformed response)
#
# If you see any of these, the search backend is broken.
import requests
# Quick test of the default Hermes search endpoint:
try:
resp = requests.get('http://localhost:8080/search?q=test', timeout=10)
print(f'Status: {resp.status_code}')
print(f'Results: {len(resp.json().get("results", []))}')
except Exception as e:
print(f'Search broken: {e}')Paso 2: Cree la función de búsqueda de reemplazo
Cree un reemplazo directo que coincida con la interfaz de la herramienta de búsqueda de Hermes. La función toma una cadena de consulta y devuelve resultados en el formato que espera Hermes.
import requests, os
SCAVIO_KEY = os.environ['SCAVIO_API_KEY']
def hermes_search_replacement(query: str, num_results: int = 5) -> dict:
"""Drop-in replacement for broken Hermes search tool.
Returns results in Hermes-compatible format."""
try:
resp = requests.post('https://api.scavio.dev/api/v1/search',
headers={'x-api-key': SCAVIO_KEY, 'Content-Type': 'application/json'},
json={'query': query, 'country_code': 'us'},
timeout=15)
resp.raise_for_status()
data = resp.json()
results = [{
'title': r['title'],
'url': r['link'],
'content': r.get('snippet', ''),
} for r in data.get('organic_results', [])[:num_results]]
return {'results': results}
except Exception as e:
return {'results': [], 'error': str(e)}
# Test the replacement:
result = hermes_search_replacement('current bitcoin price')
print(f'Results: {len(result["results"])}')
for r in result['results']:
print(f' {r["title"]}')Paso 3: Parchear el registro de la herramienta de búsqueda Hermes
Anule la herramienta de búsqueda predeterminada en la configuración de su agente Hermes. Esto reemplaza el backend roto sin modificar el código fuente de Hermes.
# Option 1: Override in your agent setup script
# Find where Hermes registers its search tool and replace it:
def register_fixed_search(agent):
"""Replace the broken Hermes search with working API."""
# Remove the broken tool
if hasattr(agent, 'tools'):
agent.tools = {name: tool for name, tool in agent.tools.items()
if name != 'web_search'}
# Register the working replacement
agent.register_tool(
name='web_search',
description='Search the web for current information.',
function=hermes_search_replacement,
parameters={
'query': {'type': 'string', 'description': 'Search query'},
'num_results': {'type': 'integer', 'description': 'Number of results', 'default': 5}
}
)
print('Search tool replaced successfully')
# Option 2: Environment variable override
# Some Hermes configs support:
# HERMES_SEARCH_BACKEND=custom
# HERMES_SEARCH_ENDPOINT=https://api.scavio.dev/api/v1/searchPaso 4: Verifique que la solución funcione de principio a fin
Ejecute consultas de prueba a través del agente Hermes parcheado para confirmar que la búsqueda funciona correctamente. Pruebe casos extremos como resultados vacíos y consultas largas.
def verify_search_fix():
test_cases = [
('current bitcoin price', True),
('best python frameworks 2026', True),
('xyznonexistentquery12345', False), # should return empty gracefully
('a' * 500, False), # very long query
]
passed = 0
for query, expect_results in test_cases:
result = hermes_search_replacement(query)
has_results = len(result.get('results', [])) > 0
has_error = 'error' in result
if expect_results and has_results:
status = 'PASS'
passed += 1
elif not expect_results and not has_error:
status = 'PASS'
passed += 1
else:
status = 'FAIL'
print(f'[{status}] "{query[:40]}" -> {len(result.get("results", []))} results')
print(f'\n{passed}/{len(test_cases)} tests passed')
print(f'Cost: ${len(test_cases) * 0.005:.3f}')
verify_search_fix()Ejemplo en Python
import os, requests
SCAVIO_KEY = os.environ['SCAVIO_API_KEY']
def hermes_search(query: str, num_results: int = 5) -> dict:
try:
resp = requests.post('https://api.scavio.dev/api/v1/search',
headers={'x-api-key': SCAVIO_KEY, 'Content-Type': 'application/json'},
json={'query': query, 'country_code': 'us'}, timeout=15)
results = [{'title': r['title'], 'url': r['link'], 'content': r.get('snippet', '')}
for r in resp.json().get('organic_results', [])[:num_results]]
return {'results': results}
except Exception as e:
return {'results': [], 'error': str(e)}
# Quick test
for q in ['bitcoin price', 'python tutorial', 'nonexistent12345']:
r = hermes_search(q)
print(f'{q}: {len(r["results"])} results')Ejemplo en JavaScript
const SCAVIO_KEY = process.env.SCAVIO_API_KEY;
async function hermesSearch(query, numResults = 5) {
try {
const resp = await fetch('https://api.scavio.dev/api/v1/search', {
method: 'POST',
headers: { 'x-api-key': SCAVIO_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({ query, country_code: 'us' })
});
const data = await resp.json();
return { results: (data.organic_results || []).slice(0, numResults)
.map(r => ({ title: r.title, url: r.link, content: r.snippet || '' })) };
} catch (e) {
return { results: [], error: e.message };
}
}
async function main() {
for (const q of ['bitcoin price', 'python tutorial']) {
const r = await hermesSearch(q);
console.log(`${q}: ${r.results.length} results`);
}
}
main();Salida esperada
Search broken: TimeoutError: Search request timed out after 10s
Results: 5
Bitcoin Price Today - Live BTC Chart
BTC/USD - Bitcoin Price & Market Cap
[PASS] "current bitcoin price" -> 5 results
[PASS] "best python frameworks 2026" -> 5 results
[PASS] "xyznonexistentquery12345" -> 0 results
[PASS] "aaaaaaaaaa..." -> 0 results
4/4 tests passed
Cost: $0.020