HHermes Explained

Operations

Provider Switching

Choosing models per task and falling back when providers fail or cost too much.

Importance 4/53 backlinks1 source refs

Provider Switching

What it is

Choosing models per task and falling back when providers fail or cost too much.

In plain terms

It works a bit like a phone call that automatically forwards to a backup line the moment the first number stops picking up, so the caller never even hears a busy signal. Provider switching lets Hermes swap which model is answering mid-conversation when the current one fails, so the failure becomes invisible instead of a dead end.

Why it matters

The choice of which model handles a given task isn’t fixed at setup time under provider switching — it can route by task type or cost budget, and fall back automatically if a provider errors or times out. Cost-aware automation depends heavily on this: a cheap, fast model can handle a routine check while a more capable one is reserved for tasks that actually need it. Retry-and-fallback leans on the same mechanism when a model call fails outright, rather than letting the turn simply error.

How it works

Hermes classifies every failed API call into a specific reason - rate limit, billing or quota, server overload, timeout, and others - and that classification decides what happens next rather than treating every error identically (agent/error_classifier.py). When a call fails, try_activate_fallback() walks an ordered list of backup provider/model pairs one at a time, skipping any entry already marked unavailable this session or that would just retry the same provider/model that already failed, and arming a short cooldown once the whole chain is exhausted (agent/chat_completion_helpers.py). That chain is user-configured: hermes fallback add appends a provider/model pair to fallback_providers in ~/.hermes/config.yaml, merging it with any legacy single-entry config, while list, remove, and clear manage it from the same store (hermes_cli/fallback_cmd.py, hermes_cli/fallback_config.py).

A concrete example

You’ve set Anthropic as your primary provider and added two fallback entries - a cheaper OpenRouter model, then a local Ollama model - using hermes fallback add.

  1. One evening, Anthropic returns a rate-limit error mid-conversation.
  2. Hermes classifies the error and automatically activates the first fallback entry instead of showing you a failure.
  3. Your conversation continues on the OpenRouter model, and you only notice the switch because a status line mentions it.

How it connects

This note belongs to the Operations family. Its closest neighboring concepts are: Local Models, Cost Control, Agent Runtime, Personal OS.

Source evidence

  • vendor/hermes-agent/run_agent.py:1892-1902#AIAgent._flush_messages_to_session_db — Verified Source Map evidence for AIAgent. AIAgent uses thin forwarding methods to delegate system-prompt construction to agent.system_prompt.build_system_prompt, API kwargs construction to the chat-completion helper, and streaming requests to interruptible_streaming_api_call.

Workflows

  • Cost-Aware Automation
  • Ten Underused Hermes Features That Reveal Its Real Power