Hermes: Setup and First Loop

What You'll Need

⏱ Time: 20 minutes  |  📋 Tasks:

• Python 3.10+ installed (python --version to check)
• An OpenAI API key (or Anthropic, or any provider Hermes supports)
• Docker from Lesson 2 (optional, for sandboxing)
• A terminal open in a project directory

What Is Hermes?

Hermes is a minimal autonomous agent framework. It's a Python library that gives a language model a perceive → decide → act → repeat loop with configurable tools, model endpoints, and logging.

What makes Hermes different from the big platforms:

• Lightweight — install it with pip, no Docker required (though you can add Docker for sandboxing). Single binary feel.
• Config-driven — define your model, tools, and task in a YAML or JSON config file. No code to write unless you need a custom tool.
• Transparent — every loop iteration is logged. You can see what the model perceived, what it decided, and what action it took.
• Single-agent focused — Hermes runs one agent loop at a time. No multi-agent orchestration, no fleet management. That simplicity makes it ideal for learning the loop pattern.

Think of Hermes as the training wheels for autonomous agents. It gives you the core loop with minimal ceremony, so you can focus on understanding the pattern before moving to more complex platforms.

Step 1: Install

Open a terminal and run:

pip install hermes-agent

That's it. Confirm it worked:

hermes --version

If you see a version number, you're ready.

Step 2: Configure a Model Provider

Hermes needs to know which model to use and how to authenticate. Create a file called hermes-config.yaml:

model:
  provider: openai
  name: gpt-4o-mini
  api_key: "${OPENAI_API_KEY}"

Set the environment variable with your API key:

# macOS / Linux
export OPENAI_API_KEY="sk-..."

# Windows PowerShell
$env:OPENAI_API_KEY = "sk-..."

Hermes reads the key from the environment. Never put the key directly in the config file — that's how keys get committed to git by accident.

Step 3: Define a Tool

A tool is something the agent can call. Hermes comes with a few built-in tools (file read, file write, web fetch), but let's add a custom one to see how it works.

Add a tools section to your config file:

model:
  provider: openai
  name: gpt-4o-mini
  api_key: "${OPENAI_API_KEY}"

tools:
  - name: search_files
    description: "Search for files by name pattern in a directory"
    command: find  -name "" 2>/dev/null
    parameters:
      dir:
        type: string
        description: "Directory to search in"
      pattern:
        type: string
        description: "Filename pattern, e.g. *.txt or report-*"

This tool wraps the Unix find command. The agent can call it with a directory path and a filename pattern, and get a list of matching files back. The parameters are injected into the command template — that's the and syntax.

Step 4: Write a Task Goal

Now we give the agent something to do. Create task.yaml:

goal: |
  Search the /workspace directory for all Markdown files (*.md).
  Read each one and summarize what it covers in 2-3 sentences.
  Write the summaries to /workspace/summary.md.

max_iterations: 15
max_cost: 0.50

Notice the guardrails: max_iterations stops the loop after 15 turns no matter what. max_cost stops it if the API spend exceeds $0.50. These are your safety net — the agent cannot run forever or blow through your budget.

Step 5: Run It

From the terminal, run:

hermes run --config hermes-config.yaml --task task.yaml

Hermes will:

1. Perceive — Call search_files on /workspace with pattern *.md
2. Decide — Look at the file list and decide which to read first
3. Act — Read each file (using the built-in file_read tool)
4. Repeat — Keep going until all files are summarized, then write the output

Each step is logged to stdout. Watch the loop unfold:

┌─ Iteration 1 ──────────────────────┐
│ Perceive: searching Markdown files │
│ Result: found 3 files              │
│ Decide: read file 1 (readme.md)    │
└────────────────────────────────────┘
┌─ Iteration 2 ──────────────────────┐
│ Perceive: reading readme.md        │
│ Result: 245 lines                  │
│ Decide: summarize and move to file │
└────────────────────────────────────┘

The Output

When the agent finishes, open /workspace/summary.md. You should see a summary of each Markdown file the agent found, written in natural language. If the agent hit the iteration limit before finishing, you'll see partial output — and you can increase max_iterations for the next run.

Hermes vs Other Loop Frameworks

Hermes wins on simplicity. It's the fastest way to get an autonomous loop running. Openclaw Fleet wins on safety and scale — it's what you'd use for production agent pipelines. AutoGPT wins on goal decomposition — if your task is vague and you need the agent to figure out the sub-steps itself, AutoGPT's approach shines.

Deliverable: Your Hermes Config Template

Here's a reusable template. Save it as hermes-task-template.yaml and adapt it for each new task:

# hermes-task-template.yaml
# Copy and customize for each autonomous task

model:
  provider: openai
  name: gpt-4o-mini  # or gpt-4o, claude-sonnet-4, etc.
  api_key: "${API_KEY}"

tools:
  - name: search_files
    description: "Find files by name pattern"
    command: find  -name "" 2>/dev/null
    parameters:
      dir: { type: string, description: "Directory to search" }
      pattern: { type: string, description: "Filename pattern" }

  - name: read_file
    description: "Read a file's contents"
    command: cat 
    parameters:
      path: { type: string, description: "Full path to the file" }

task:
  goal: "Describe what you want the agent to do"
  max_iterations: 15
  max_cost: 0.50
  output: "result.md"

Start with max_iterations: 15 and max_cost: 0.50. Adjust upward as you gain confidence. Hermes is designed to be safe by default — tighten the limits for learning, then gradually expand as you understand the agent's behavior.

Try It

Run the full walkthrough above. Install Hermes, create the config files, and run a real autonomous task. When it finishes, open the output file and inspect the work. Then change the task goal to something you actually need done — "list all Python files in my project and count their lines," or "fetch the top story from a news site and summarize it."

The loop you just ran is the same pattern used by every autonomous agent platform. The tools change, the config format changes, but the perceive → decide → act → repeat cycle is universal. You've built it. You've run it. Now you own it.