Hermes Agent

Hermes Agent is Nous Research's agent runtime, tuned for the Hermes / Qwen tool format. It injects a large system prompt with ~60+ tools, so a long context window is a hard prerequisite.

Install

$ pip install hermes-agent
# If the pip build fails on your platform, clone and install from source in a venv:
#   git clone https://github.com/NousResearch/hermes-agent && cd hermes-agent
#   python -m venv .venv && .venv/bin/pip install -e .

Config

One-shot: rapid-mlx agents hermes --setup writes ~/.hermes/config.yaml. By hand, the exact template rapid-mlx 0.10.3 emits:

# ~/.hermes/config.yaml
model:
  provider: "custom"
  default: "default"
  base_url: "http://localhost:8000/v1"
  context_length: 32768
  max_tokens: 4096
platform_toolsets:
  cli: [terminal, file, code_execution, web, browser, skills]

Run

$ rapid-mlx serve qwen3.5-9b-4bit \
    --tool-call-parser hermes --enable-auto-tool-choice
$ hermes chat

Recommended aliases (per rapid-mlx agents hermes): qwen3.5-4b-4bit, qwen3.5-9b-4bit, gemma-4-26b-4bit, qwen3.5-35b-a3b, qwen3.6-35b-4bit.

Integration harness (test_hermes.py)

The deep flow at tests/integrations/test_hermes.py writes ~/.hermes/config.yaml to point at the running server, then drives hermes chat -q <query> -Q in non-interactive mode. Because Hermes injects 60+ tools into every turn, small models can run out of context — the harness treats "context too small for the tool block" as SKIP, not FAIL.

Gotchas

• Long context is a hard prerequisite. Hermes' tool block eats several thousand tokens by itself. Set context_length: 32768 or higher; aliases with 8k context will error out mid-turn.
• todo tool conflict on Gemma 4. Hermes injects a todo tool that races Gemma 4's own reasoning format. Fix: exclude todo from platform_toolsets, or use Hermes' -t flag.
• Gemma 4 "calling tool mimicry". After many tool turns Gemma 4 parrots Hermes UI text. Fixed in rapid-mlx v0.4.3.

Empirical

The hermes-agent row of the integration matrix is ✅ on Qwen 3.6, Gemma 4, and gpt-oss; DeepSeek R1-Distill XFAIL(arch). Deep flow assertions in test_hermes.py cover plain, streaming, single tool, multi-tool, and structured output.

See also