Sókrates Wiki

Hermes Web Search Toolset

3 min read

Hermes Web Search Toolset

Summary

The Hermes Web Search Toolset provides the Hermes agent with native capabilities to interact with the live web through web_search, web_extract, and web_crawl tools. It supports multiple backends, primarily Tavily for optimized AI retrieval and Firecrawl for self-hosted, on-premises deployments.

Details

Hermes includes a built-in web toolset that does not require an external Model Context Protocol (MCP) server. These tools are enabled by including "web" or "all" in the toolsets list within the hermes.nix configuration. While the tools are native to the agent, they require an external API provider or a self-hosted instance to perform the actual web traversal and indexing.

Supported Backends

Hermes is designed to auto-detect the search backend based on the environment variables provided. Supported providers include:

  • Tavily: The current preferred backend for development. It is purpose-built for AI agents, providing pre-extracted and summarized results that reduce token consumption.
  • Firecrawl: Identified as the long-term production solution. Firecrawl is self-hostable, which aligns with the Sokrates project’s goal of maintaining an on-premises, air-gapped-capable stack. It can be deployed as a container within the Sokrates Docker stack, using FIRECRAWL_API_URL to point the agent to the local instance.
  • Parallel and Exa: Additional supported providers that Hermes can utilize if the respective API keys are present.

Configuration and Secrets Management

The configuration of the web toolset involves both the NixOS module settings and the secure management of API keys.

In hermes.nix, the backend can be explicitly set:

settings = {
  web = {
    backend = "tavily"; # Options: tavily, firecrawl, parallel, exa
  };
};

Secrets management for these tools follows a specific idempotent workflow to ensure keys are not lost or incorrectly mapped during NixOS rebuilds. API keys (e.g., TAVILY_API_KEY) must be appended to the persistent secrets file on the host:

  • Path: /var/lib/sokrates/secrets/hermes/hermes.env

The hermes-agent systemd service utilizes an ExecStartPre merge script. This script takes the secrets from the persistent directory and merges them into the agent’s local environment file at ~/.hermes/.env. This approach was adopted after several iterations (documented in git history) to solve issues where Hermes failed to read standard os.environ variables or where symlinks were clobbered during deployment.

Deployment Workflow

To activate or update web search capabilities:

  1. Add the API key to /var/lib/sokrates/secrets/hermes/hermes.env.
  2. Update the hermes.nix configuration if a specific backend choice is required.
  3. Run sudo nixos-rebuild switch --flake .#sokrates-dev (or sokrates-box).
  4. Restart the service: systemctl restart hermes-agent.

Graph View

Backlinks