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, auto-detecting your served model's real context window. A representative template (context_length shown for a 256K-window model):

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

Run

$ rapid-mlx serve qwen3.5-9b-4bit
$ hermes chat

Recommended aliases (per rapid-mlx agents hermes): qwen3.5-4b-4bit, qwen3.5-9b-4bit, gemma-4-26b-4bit, qwen3.5-35b-4bit, 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 refuses to start below 64K. Hermes' 60+ tool block eats several thousand tokens by itself, so it rejects any model whose context_length is under 64000 ("context window … below the minimum 64,000 required by Hermes Agent"). Set context_length to your model's real window (e.g. 262144 for Qwen 3.6) — --setup does this automatically. A stale 32768 value copied by hand will be refused up front.
• 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