keepcalculator

06 Numbers and Powers

Enable Web Search in Hermes Agent: Step-by-Step

Card No. 06·81583 · Updated · Standard formula, shown below

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

  1. Locate the configuration file. On most installations, the file is at /etc/hermes/hermes_config.yaml or ~/.hermes/hermes_config.yaml. If you’re using a Docker container, it’s typically mounted at /app/config.yaml. Run hermes config --path to find the exact location.
  2. Open the configuration file in a text editor with administrative privileges (e.g., sudo nano hermes_config.yaml).
  3. Find the web_search section. Scroll down until you see a block starting with web_search:. If it doesn’t exist, add it at the top level (indentation matters).
  4. Set enabled: true. Under web_search:, add or modify the line enabled: true. This turns on the feature.
  5. Choose a search provider. Under web_search:, set the provider field. Options include duckduckgo (no API key needed), bing, google, or serpapi. For example: provider: duckduckgo.
  6. Add your API key (if using a custom provider). If you chose bing, google, or serpapi, add a line like api_key: YOUR_API_KEY_HERE. Replace YOUR_API_KEY_HERE with the actual key from your provider’s dashboard.
  7. 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.
  8. Configure timeout and retries (optional). To avoid long hangs, set timeout: 10 (in seconds) and retries: 2. These are good defaults for most networks.
  9. Save the file. In nano, press Ctrl+O, then Enter, then Ctrl+X to exit.
  10. Restart Hermes Agent. Run systemctl restart hermes-agent (if using systemd) or hermes restart. For Docker, run docker restart hermes-agent-container.
  11. Verify the configuration. Run hermes config --check to ensure the YAML is valid. If there are errors, fix them and restart again.
  12. 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 with hermes logs --tail 20 for a line like Web 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 duckduckgoo will cause an error. Double-check the exact spelling.
  • Missing API key: If you select bing or google but 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 duckduckgo provider for quick testing—it requires no API key and works out of the box.
  • Set max_results to 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_var option).
  • 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:

  1. Check the logs. Run hermes logs --tail 50 and look for errors like web_search: disabled or API key invalid. The error message usually points to the root cause.
  2. Validate YAML syntax. Use a YAML linter (e.g., python -c "import yaml; yaml.safe_load(open('hermes_config.yaml'))") to catch syntax errors.
  3. Test the API key separately. Use curl to 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.
  4. Verify the provider is set correctly. Run hermes config --show | grep provider to see the active provider. If it shows a different one, the config wasn’t saved properly.
  5. 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.
  6. Ensure Hermes is up to date. Run hermes --version and compare with the latest release. Older versions may not support web search—update with pip install --upgrade hermes-agent or your package manager.
  7. 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

The whole Numbers and Powers drawer →