This guide walks you through enabling web search in Hermes Agent, a task automation tool that can browse the internet to gather information, verify facts, and enrich responses. You’ll configure the search provider, set permissions, and test the integration. Before starting, ensure you have admin access to the Hermes Agent configuration file and an API key for a search service if you plan to use a custom provider.
What You’ll Need
- Hermes Agent installed and running (version 1.5 or later recommended).
- Administrator or owner access to the Hermes configuration file (usually
hermes_config.yaml). - An API key from a search provider (e.g., Bing Web Search, Google Custom Search, or SerpAPI) if you want to use a custom search engine. Alternatively, you can use the built-in DuckDuckGo integration that requires no key.
- Basic familiarity with editing YAML files and restarting services.
Step-by-Step
- Locate the configuration file. On most installations, the file is at
/etc/hermes/hermes_config.yamlor~/.hermes/hermes_config.yaml. If you’re using a Docker container, it’s typically mounted at/app/config.yaml. Runhermes config --pathto find the exact location. - Open the configuration file in a text editor with administrative privileges (e.g.,
sudo nano hermes_config.yaml). - Find the
web_searchsection. Scroll down until you see a block starting withweb_search:. If it doesn’t exist, add it at the top level (indentation matters). - Set
enabled: true. Underweb_search:, add or modify the lineenabled: true. This turns on the feature. - Choose a search provider. Under
web_search:, set theproviderfield. Options includeduckduckgo(no API key needed),bing,google, orserpapi. For example:provider: duckduckgo. - Add your API key (if using a custom provider). If you chose
bing,google, orserpapi, add a line likeapi_key: YOUR_API_KEY_HERE. ReplaceYOUR_API_KEY_HEREwith the actual key from your provider’s dashboard. - Set the number of results (optional). You can limit how many results Hermes fetches per query by setting
max_results: 5(adjust the number). The default is 3. - Configure timeout and retries (optional). To avoid long hangs, set
timeout: 10(in seconds) andretries: 2. These are good defaults for most networks. - Save the file. In nano, press
Ctrl+O, thenEnter, thenCtrl+Xto exit. - Restart Hermes Agent. Run
systemctl restart hermes-agent(if using systemd) orhermes restart. For Docker, rundocker restart hermes-agent-container. - Verify the configuration. Run
hermes config --checkto ensure the YAML is valid. If there are errors, fix them and restart again. - Test web search. In a terminal, run a simple query:
hermes ask "What is the capital of France?". If web search is working, the response should include a citation or a note that it used web search. Alternatively, check the logs withhermes logs --tail 20for a line likeWeb search enabled.
Common Mistakes
- Incorrect indentation: YAML is strict. The
web_search:block must be at the top level, and all sub-keys must be indented consistently (usually two spaces). A single extra space breaks the config. - Using an invalid provider name: Typo like
duckduckgoowill cause an error. Double-check the exact spelling. - Missing API key: If you select
bingorgooglebut don’t provide an API key, Hermes will fail to authenticate. Ensure the key is correctly pasted with no extra spaces. - Forgetting to restart: Changes to the config file only take effect after a restart. If you don’t restart, the old settings remain.
- Firewall blocking outbound requests: If web search times out, your network might be blocking the search API. Check that outbound HTTPS (port 443) is allowed.
Tips
- Use the
duckduckgoprovider for quick testing—it requires no API key and works out of the box. - Set
max_resultsto a lower number (e.g., 3) to reduce response time and token usage. - If you’re using a custom provider, generate a dedicated API key with quotas to avoid using your main key.
- Keep your API key secure—don’t commit the config file to a public repository. Use environment variables if supported (check Hermes docs for
env_varoption). - Test with a simple, factual query first to confirm the integration works before relying on it for complex tasks.
Troubleshooting
If web search isn’t working after following the steps, try these checks in order:
- Check the logs. Run
hermes logs --tail 50and look for errors likeweb_search: disabledorAPI key invalid. The error message usually points to the root cause. - Validate YAML syntax. Use a YAML linter (e.g.,
python -c "import yaml; yaml.safe_load(open('hermes_config.yaml'))") to catch syntax errors. - Test the API key separately. Use
curlto call the search API directly. For Bing, run:curl -H "Ocp-Apim-Subscription-Key: YOUR_KEY" "https://api.bing.microsoft.com/v7.0/search?q=test". If you get a 401, the key is wrong or expired. - Verify the provider is set correctly. Run
hermes config --show | grep providerto see the active provider. If it shows a different one, the config wasn’t saved properly. - Check network connectivity. From the server running Hermes, try
curl https://api.duckduckgo.com(or your provider’s endpoint). If it fails, there’s a network issue. - Ensure Hermes is up to date. Run
hermes --versionand compare with the latest release. Older versions may not support web search—update withpip install --upgrade hermes-agentor your package manager. - If using Docker, check volume mounts. Make sure the config file is mounted correctly and you edited the file inside the container, not just on the host.
Frequently Asked Questions
Does web search work with any provider?
Hermes supports DuckDuckGo, Bing, Google, and SerpAPI. DuckDuckGo works without an API key; others require a valid key.
Can I use web search without an API key?
Yes, the DuckDuckGo provider is free and keyless. Just set provider: duckduckgo and enable the feature.
How do I change the number of search results returned?
Set max_results under the web_search section to your desired integer (e.g., max_results: 5).
Will enabling web search slow down my agent?
It can add a few seconds per query, especially with high max_results. Adjust timeout and max_results to balance speed and accuracy.
Is my API key stored securely?
It’s stored in plain text in the config file. To secure it, set file permissions (e.g., chmod 600) and consider using environment variables if your version supports them.
Can I disable web search later?
Yes, set enabled: false in the web_search section and restart Hermes Agent.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.
More cards in this drawer
- Skip Ryobi and Milwaukee? Harbor Freight Tools to Buy
- Funny Subreddits That Make You Laugh
- Why Retro Gaming Is Still Worth Playing Today
- Neptune Facts That Will Blow Your Mind
- Survival Crafting Game Fatigue: Why & How to Fix It
- Sell Your EV Now Before Prices Plummet?