Troubleshooting the Hermes Research Agent Web Search Workflow

by

While building out a specialized Researcher agent in Hermes, I ran into an issue where the agent appeared unable to properly search the web.

The Researcher profile itself was working correctly. Its identity, SOUL configuration, local model, memory, and workspace access were all functioning as expected. The problem appeared specifically when the agent was asked to perform web research.

The Problem

The expected workflow for the Researcher agent was:

Research Question
      ↓
web_search
      ↓
Find relevant sources
      ↓
web_extract
      ↓
Read source content
      ↓
Analyze and summarize

Instead, the agent repeatedly attempted to call:

web_extract

without first calling:

web_search

This happened even when the prompt explicitly instructed the agent to use web_search first.

Initial Suspicions

Several possible causes were investigated:

  • A firewall or outbound network restriction on TrueNAS
  • DNS resolution problems inside the Hermes Docker container
  • An issue with the Exa search provider
  • A Hermes tool-registration problem
  • A tool-calling compatibility problem with the local Qwen model

Firewall and Network Testing

The Hermes container was tested directly against both the Hermes documentation site and the Exa API.

getent hosts hermes-agent.nousresearch.com
curl -I https://hermes-agent.nousresearch.com/docs/

getent hosts api.exa.ai
curl -I https://api.exa.ai

The Hermes documentation site returned:

HTTP/2 200

The Exa API returned:

HTTP/2 404

A 404 response from the Exa API was actually useful in this test because it proved that the container could successfully resolve DNS, establish a TCP connection, complete TLS negotiation, and reach the remote HTTPS service.

This ruled out the firewall as the primary cause.

Verifying the Hermes Tool Configuration

The Researcher profile showed the Hermes web toolset as enabled:

✓ enabled  web  Web Search & Scraping

The profile configuration included:

platform_toolsets:
  cli: [file, memory, skills, terminal, vision, web]

Hermes was also inspected internally to verify the tool definitions being exposed to the model.

The result was:

MODEL-VISIBLE ['web_extract', 'web_search']
RAW ['web_extract', 'web_search']

This confirmed that Hermes was correctly exposing both tools to the model.

The Actual Cause

The important discovery was that the dedicated search toolset was still listed under the Researcher profile’s disabled toolsets.

When the agent was tested using only the search toolset, Hermes returned:

I cannot search the web directly.

No tools were called.

After removing search from the disabled toolsets, the exact same test immediately produced:

preparing web_search...
search Hermes Agent Kanban documentation

This confirmed that web_search itself was working correctly.

The Fix

The search entry was removed from the Researcher profile’s disabled toolsets.

The Researcher CLI tool configuration was then updated to explicitly include both search and web:

platform_toolsets:
  cli: [file, memory, search, skills, terminal, vision, web]

After this change, a normal Researcher session successfully started using web search without requiring special command-line overrides.

The resulting tool flow included:

web_search
web_search
web_extract
web_search

This demonstrated that the Researcher agent could now naturally discover web sources.

A Second Issue: Search vs. Extraction

Once web search was functioning, another limitation became clear.

DuckDuckGo was configured as the Researcher agent’s search backend. It successfully handled:

web_search

However, DuckDuckGo is a search-only backend and does not provide page extraction.

As a result, attempts to use:

web_extract

returned a message indicating that the DuckDuckGo backend could search but could not retrieve full page content.

Current Working Architecture

The Researcher agent is now successfully performing web discovery:

Researcher
    ↓
web_search
    ↓
DuckDuckGo
    ↓
Search Results

The remaining work is to configure a separate extraction-capable backend for:

web_extract

The intended final workflow will look like:

Research Question
      ↓
web_search
      ↓
DuckDuckGo
      ↓
Relevant Sources
      ↓
web_extract
      ↓
Exa / Firecrawl / another extraction backend
      ↓
Source Content
      ↓
Researcher Analysis

What Was Confirmed

  • The Researcher Hermes profile is functioning correctly.
  • The Researcher SOUL configuration is loading correctly.
  • The Qwen model can successfully call Hermes tools.
  • Hermes exposes both web_search and web_extract.
  • TrueNAS and the Hermes Docker container have working outbound internet connectivity.
  • DuckDuckGo web search works correctly.
  • The firewall was not blocking the Researcher agent.

Remaining Work

The final step is to configure an extraction-capable backend so that Researcher can not only discover sources but also read and analyze the full content of those sources.

The target configuration is:

Search Backend:
DuckDuckGo

Extraction Backend:
Exa, Firecrawl, or another supported extractor

Once that is complete, the Researcher agent should have the full web research workflow required for the broader Hermes AI Team project.

Final Result

The issue turned out to be a useful debugging exercise because it validated several important parts of the architecture.

The Researcher agent is now able to independently perform web searches using the local Hermes environment and local Qwen model. The remaining extraction configuration is a relatively small step compared with the original problem.

More importantly, the troubleshooting confirmed that the underlying design is sound:

Hermes
  ↓
Researcher Profile
  ↓
Local Qwen Model
  ↓
Web Research Tools
  ↓
Shared Agent Workspace

That moves the project one step closer to the larger goal: building a Hermes-based AI team where specialized agents can independently research, engineer, document, and collaborate on tasks assigned by a Chief of Staff agent.

Leave a Comment