HHermes Explained

Runtime

Retry And Fallback

The operational pattern for recovering when a model or tool path fails.

Importance 3/53 backlinks1 source refs

Retry And Fallback

What it is

The operational pattern for recovering when a model or tool path fails.

In plain terms

A building’s backup generator kicks in the instant the power flickers, so the lights never go out for anyone inside, even though the electricity now comes from a different source. Hermes keeps a line of backup models on standby the same way: when the one currently performing — answering, calling tools — stumbles, another one already up to speed steps in without the conversation going dark.

Why it matters

A single flaky provider response doesn’t have to take down an entire cron run or conversation — a failed model call can retry, or reroute to a fallback provider, before the turn gives up entirely. For an unattended VPS deployment running jobs overnight, that’s the difference between a transient API hiccup and a missed daily briefing nobody notices until morning. The same pattern covers failed tool calls too, so a dropped web search doesn’t automatically end a turn that could otherwise recover.

How it works

Every failed API call runs through classify_api_error (agent/error_classifier.py), which sorts it into one of over a dozen reasons — rate limit, billing exhaustion, server overload, context overflow, model not found — each carrying its own recovery hint: retry, rotate credential, compress, or fall back. Straightforward retries use jittered, provider-aware backoff (agent/retry_utils.py) so multiple sessions hitting the same limited provider don’t all retry in lockstep. When retries are exhausted, or the error itself calls for it, try_activate_fallback (agent/chat_completion_helpers.py) walks a configured fallback chain one entry at a time, swapping the active client, model, and provider in place so the rest of the turn loop continues unaware. A short cooldown after a rate-limit-triggered fallback keeps the agent from immediately bouncing back to a provider that just rejected it.

A concrete example

An unattended VPS deployment runs a 2am research job. The configured primary provider returns a 429 partway through. Hermes classifies it as a rate limit, retries twice with a jittered delay, then — still blocked — activates the next entry in the fallback chain set up with hermes fallback add, swapping providers mid-turn. The job finishes and writes its report as normal; the only trace of the hiccup is a status line in the log, discovered the next morning rather than a missed briefing.

How it connects

This note belongs to the Runtime family. Its closest neighboring concepts are: Model Call, Compression, 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

  • No first-pass workflow mapping yet; this concept still appears in the vault graph through articles and source evidence.
  • Mastering Hermes Desktop: From Local Chat App to an Always-On Agent Control Center
  • From Zero to a Personal AI Assistant: Building Hermes on a VPS Without Creating a Mess