Hermes agent needs a search backend to ground its responses in real data. This tutorial configures Scavio as the search provider for Hermes, registers the search tool, and tests it with common agent workflows. The setup takes under 5 minutes and costs $0.005 per search call.
Prerequisites
- Hermes agent installed
- Python 3.8+
- A Scavio API key from scavio.dev
- Basic familiarity with Hermes agent config
Walkthrough
Step 1: Register search tool with Hermes
Create the search tool definition that Hermes can call.
Python
import os, requests, json
API_KEY = os.environ['SCAVIO_API_KEY']
SH = {'x-api-key': API_KEY, 'Content-Type': 'application/json'}
# Hermes tool definition
hermes_search_tool = {
'type': 'function',
'function': {
'name': 'web_search',
'description': 'Search the web for current information. Returns structured results with title, link, and snippet. Use for any question about current events, recent data, or facts you need to verify.',
'parameters': {
'type': 'object',
'properties': {
'query': {'type': 'string', 'description': 'Search query'},
'num_results': {'type': 'integer', 'description': 'Number of results (1-10)', 'default': 5}
},
'required': ['query']
}
}
}
def web_search(query, num_results=5):
data = requests.post('https://api.scavio.dev/api/v1/search',
headers=SH, json={'query': query, 'country_code': 'us', 'num_results': num_results}).json()
return [{'title': r.get('title', ''), 'link': r.get('link', ''),
'snippet': r.get('snippet', '')} for r in data.get('organic_results', [])[:num_results]]
# Test
results = web_search('hermes agent configuration 2026')
print(f'Tool registered. Test: {len(results)} results')
for r in results[:2]:
print(f' {r["title"]}')
print(json.dumps(hermes_search_tool, indent=2))Step 2: Add MCP configuration for Hermes
Configure the MCP server in Hermes config file.
Python
# Hermes MCP configuration
hermes_mcp = {
'mcpServers': {
'scavio-search': {
'command': 'npx',
'args': ['-y', 'scavio-search-mcp'],
'env': {
'SCAVIO_API_KEY': os.environ.get('SCAVIO_API_KEY', '')
}
}
}
}
# Save to Hermes config directory
config_dir = os.path.expanduser('~/.hermes')
os.makedirs(config_dir, exist_ok=True)
config_path = os.path.join(config_dir, 'mcp.json')
print(f'Hermes MCP config: {config_path}')
print(json.dumps(hermes_mcp, indent=2))
print(f'\nRestart Hermes to load the search MCP server.')
print(f'The agent will now have access to web_search tool.')Step 3: Test Hermes agent with search grounding
Run test queries to verify Hermes uses the search tool correctly.
Python
def simulate_hermes_workflow(task):
"""Simulate how Hermes uses the search tool for a task."""
print(f'\n=== Hermes Agent: "{task}" ===')
# Step 1: Agent decides to search
print(f' [Think] Need current information. Calling web_search.')
results = web_search(task)
print(f' [Search] {len(results)} results returned')
# Step 2: Agent processes results
context = '\n'.join([f'{r["title"]}: {r["snippet"]}' for r in results[:3]])
print(f' [Context] {len(context)} chars of grounding data')
# Step 3: Agent formulates response
print(f' [Answer] Based on {len(results)} sources...')
for r in results[:3]:
print(f' Source: {r["title"][:50]}')
print(f' [Cost] $0.005')
tasks = [
'what are the best python web frameworks in 2026',
'latest kubernetes security vulnerabilities',
'compare AWS Lambda vs Google Cloud Run pricing',
]
for task in tasks:
simulate_hermes_workflow(task)
print(f'\nTotal test cost: ${len(tasks) * 0.005:.3f}')Python Example
Python
import os, requests
SH = {'x-api-key': os.environ['SCAVIO_API_KEY'], 'Content-Type': 'application/json'}
def hermes_search(query):
data = requests.post('https://api.scavio.dev/api/v1/search',
headers=SH, json={'query': query, 'country_code': 'us'}).json()
for r in data.get('organic_results', [])[:3]:
print(f' {r["title"]}: {r.get("snippet", "")[:60]}')
hermes_search('hermes agent web search setup')
print('Cost: $0.005')JavaScript Example
JavaScript
const SH = { 'x-api-key': process.env.SCAVIO_API_KEY, 'Content-Type': 'application/json' };
const data = await fetch('https://api.scavio.dev/api/v1/search', {
method: 'POST', headers: SH,
body: JSON.stringify({ query: 'hermes agent web search', country_code: 'us' })
}).then(r => r.json());
(data.organic_results || []).slice(0, 3).forEach(r => console.log(r.title));Expected Output
JSON
Tool registered. Test: 5 results
Hermes Agent: Getting Started Guide
Configure Hermes with MCP Servers
=== Hermes Agent: "what are the best python web frameworks in 2026" ===
[Think] Need current information. Calling web_search.
[Search] 5 results returned
[Context] 450 chars of grounding data
[Answer] Based on 5 sources...
Source: Top Python Web Frameworks 2026
[Cost] $0.005
Total test cost: $0.015