Hermes Agent Master Class Part 1: How Hermes Agent Actually Processes Work

Every AI chatbot you’ve used has the same architecture: type a message, the model generates a response.

One step. Done.

Hermes is different in a way that isn’t obvious from screenshots.

When you send it a message, it runs through a structured process – prompt assembly, provider resolution, API call, tool dispatch, result evaluation, and context persistence – before it responds.

Some messages trigger ten tool calls, each one feeding back into the model for another round of reasoning. Then the session is saved, memory is flushed, and the whole thing is ready to resume later.

This is an agent loop.

Understanding how it works is the key to understanding why this tool compounds in ways that basic chatbots do not.

Here’s what happens under the hood every time you send a message.

The Agent Loop, Not the Chat Loop

Chatbots have a simple architecture:

**user message -> model predicts -> response **

Every input is a fresh inference against static training data.

The model doesn’t run anything. It doesn’t check anything. It guesses, based on what it learned during training.

Hermes has a loop.

The AIAgent class lives in run_agent.py and handles the entire lifecycle of a single turn:

• prompt assembly

• provider selection

• API call

• tool dispatch

• compression

• fallback

• persistence

It supports three API execution modes (OpenAI chat completions, OpenAI Codex/Responses, and native Anthropic Messages) and converges them all into the same internal message format.

Here’s what happens, in order, every time you send a message:

1. Prompt assembly. The system builds your context from ten-plus layers. SOUL.md for identity. Skills for procedural knowledge. Memory and user profile snapshots. Context files from your project directory. Platform hints for where you’re chatting from. All of it assembled into three ordered tiers: stable (identity, tools, skills), context (project files), and volatile (memory, profile, timestamp).

2. Provider resolution. Maps your provider and model selection to the right API endpoint, API key, and mode. Handles 18+ providers, OAuth flows, and credential pools.

3. Preflight compression. If the conversation exceeds 50% of the model’s context window, Hermes compresses before making the API call. Middle turns are summarized, the last 20 messages are preserved intact, and a new session lineage ID is generated.

4. API call. The assembled context is sent to the model. The HTTP request runs in a background thread with an interrupt event watching it. You can cancel mid-flight with a signal, a /stop command, or by sending a new message. If the model fails with a 429 or 5xx, Hermes checks its fallback provider list and tries the next one.

5. Response parsing. If the model returns text, that’s the answer, and it gets persisted to the session store. If the model returns tool calls, the loop continues.

Where Tools Enter the Picture

Here’s the part that’s fundamentally different from a chatbot.

When a language model determines it needs to do something – run a command, search the web, write a file, read a document – it returns a tool_call instead of text.

Hermes catches that and dispatches it through a central registry at tools/registry.py.

The registry has 70+ registered tools across roughly 28 toolsets.

Each tool file calls registry.register() at import time with its name, schema, handler function, availability check, and metadata.

When a tool_call arrives:

• Agent-level tools (memory, todo, session search, delegation) are intercepted by the agent loop itself since they need direct access to agent state.

• Everything else goes through registry.dispatch(), which looks up the handler, checks availability via the tool’s check_fn, executes it, and returns the result as a JSON string.

• Errors are wrapped at two levels: registry.dispatch() catches handler exceptions, and handle_function_call() catches dispatch exceptions. The model always receives a well-formed result, never an unhandled error.

Multiple tool calls from a single model response run concurrently via a thread pool executor. The exception is tools marked as interactive, like clarify, which force sequential execution.

Once all tool results come back, they’re appended to the conversation history as tool role messages, and the loop goes back to step 3 (API call) with the new context.

This continues until the model returns a text response or hits the iteration budget.

The Prompt Architecture Is the Product

The reason Hermes gets better over time isn’t magic. It’s structural.

The system prompt is built as three ordered tiers:

• Stable. SOUL.md (your agent’s identity), tool guidance, skills, environment hints, and platform hints. This layer doesn’t change mid-conversation.

• Context. Your project’s .hermes.md or AGENTS.md or CLAUDE.md plus any caller-supplied system message. Only one project context type is loaded, discovered by priority from the working directory.

• Volatile. Memory snapshot, user profile snapshot, external memory provider block, and the current timestamp/session/model line. These update between sessions but are frozen for the duration of a single conversation.

Memory is written to disk mid-session but doesn’t mutate the cached system prompt until a rebuild path runs: new session, compression, or explicit invalidation. This keeps the prompt prefix stable for provider-side caching.

This separation is intentional.

• It means the first part of your prompt (identity, tools, skills) benefits from API-level prompt caching.

• It means memory changes don’t break the cache mid-conversation.

• It also means skills, context files, and platform hints each have a defined slot with defined precedence.

Design Choices That Matter

The documentation calls out five design principles. They’re worth knowing because they explain why Hermes behaves the way it does:

Prompt stability. The system prompt doesn’t change mid-conversation. No cache-breaking mutations unless you explicitly switch models with /model.

Observable execution. Every tool call is visible – a spinner in the CLI, progress messages in Telegram, callback updates in Discord. You can see what the agent is doing while it does it.

Interruptible. API calls and tool execution can be cancelled mid-flight. Not in a “force quit the process” way. In a “send a new message and the old request gets abandoned cleanly” way.

Platform-agnostic core. One AIAgent class serves the CLI, messaging gateways, the ACP editor integration, batch processing, and the API server. Platform differences live in the entry point, not the agent.

Loose coupling. MCP servers, plugins, memory providers, and RL environments all use registry patterns and check_fn gating. Optional subsystems don’t create hard dependencies. If a plugin fails to load, the rest of the agent still works.

What This Means for How You Use It

GIF

Understanding the agent loop changes how you think about Hermes.

You know that skills get loaded into the stable prompt tier, so they’re always available but don’t change mid-conversation.

If you want the agent to adopt new expertise, add or switch skills between sessions, not during them.

You know that context files are loaded by priority from your working directory.

The .hermes.md in your project root beats an AGENTS.md in the same directory. The CLAUDE.md only loads if there’s no .hermes.md or AGENTS.md. Structure your project context accordingly.

You know that tool calls are concurrent by default.

If you’re asking Hermes to do four independent things, it will do them simultaneously, not one at a time. Design your prompts to take advantage of that.

And you know that the iteration budget exists.

Default is 90 turns. Each tool call counts as a turn. A complex task that requires 15 tool calls eats 15 of your 90. Subagents get their own independent budgets capped at 50.

If you’re running long workflows, budget for the tool calls, not just the conversation turns.

The agent loop is the architecture that makes everything else possible.

Skills compound because they’re loaded as stable context that the model never forgets it has. Memory compounds because it’s written to disk mid-session but snapshotted at session boundaries. The tool system grows because new tools self-register at import time without needing manual wiring.

Chatbots predict the next token. Hermes runs a process.

That’s the difference that compounds.

The loop only works if it can reach your tools and persist your sessions.

This article is the first installment of my (long-overdue) Hermes Agent Master Class. It’s written with the assumption that you already have Hermes Agent installed.

If you do NOT have Hermes installed yet, start here.

New users may also want to give this article a read while you’re waiting on Part 2 of the Master Class to drop.

‘A Guide to Your First Two Weeks with Hermes Agent’. 👇

Tony Simons@tonysimons_·Jun 14 ArticleYou Installed Hermes Agent. Now What?A Guide To Your First Two Weeks With Hermes I’ve been running Hermes Agent daily for three months. Not as a demo. Not as a “let me test this for a review.” As the thing that researches my articles,…52411933K

If you found this useful, please consider giving it a bookmark and a share.

See ya in the next one! 🤘