learn-agent-architecture: A Section-by-Section Course on the Harness Around the Model

The Problem It Picks: Agency Is Not in the Model Call

A single model call returns text. It cannot run a tool, remember what happened two turns ago, or refuse to delete a file. The README states the split plainly: the model reasons, and the harness turns that reasoning into controlled action by running tools, keeping state across calls, gating side effects, and coordinating loops. That sentence is the whole thesis of the repository, and every section is an expansion of one clause in it.

The intended reader is someone who already writes code against a model API and keeps hitting the same wall: the loop is twenty lines, but the surrounding machinery is where the bugs and the design decisions live. The README argues the payoff is transferable. A coding tool, a chat assistant, and an autonomous runner, it says, mostly differ in harness choices, so learning the harness once lets you read many agents. That is a claim about reading skill, not about code reuse, and it shapes what the repository is: a set of writeups with runnable demos, not a framework.

Eight Layers and a Four-Part Lens

The sections are grouped into layers. Layer 0 is a single entry, the harness thesis, asking where agency comes from. Layer 1 covers the core loop: the agent loop itself, the tool runtime, permission and sandbox, and hooks. Layer 2 moves to complex work with planning and todos, then subagents. The README lists eight layers in total, from the basic loop up to a harness that runs itself, and the section index also names memory, context, tasks, and interfaces as topics.

Each section is written through the same lens, stated in the README as four parts: an opening on the problem the layer solves, the general mechanism and control flow, how real systems implement it, and failure modes with mitigations. That fourth part is the reason to read this rather than a design blog post. A tool runtime writeup that ends at schema dispatch tells you what to build; one that also covers what breaks when dispatch goes wrong tells you what to watch.

Section 9 does not finish in this repository. The README says it continues in a companion repo, learn-agent-memory, with ten more stages that scale its memory loop toward production. Two other companions are named: learn-deepseek-harness, for plugin seams, and EvalGrill, which turns real cases from agent applications into eval sets. The boundary is explicit, which is better than a course that quietly thins out at the hard part.

Four Systems, Pinned to Versions

The curriculum does not invent a toy agent and generalize from it. It studies four named systems, each with a stated version and a stated reason to read it. Claude Code is the frontier coding agent and is used across all sections, 0 to 23, at v2.1.88. Hermes Agent is the long-term assistant case, read for memory, skills, and always-on channels, at v2026.7.1. mini-swe-agent is the research baseline, described as one bash tool in about 150 lines, read for the smallest complete loop plus budgets and the eval harness, at v2.4.5. deepseek-harness is the plugin-first case where even the loop is a replaceable plugin, read for plugin seams, a durable session log, and ACP, at dsh-v0.1.0-rc.7.

The version pinning is the most practical thing in the README. Harness code moves, and a writeup that says how Claude Code gates a tool call is only useful if you know which build it describes. It also sets the maintenance burden you inherit as a reader: when you upgrade the real system, the section you learned from may no longer match. The README mentions OpenClaw and aider as possible future additions, so the set is expected to grow rather than freeze.

The mapping between systems and sections is uneven by design. Hermes Agent appears in sections 7, 9, 14, 16, 19, 21, and 22, which matches the claim that it is the memory and always-on example. mini-swe-agent covers 0 to 3, 8, 10, 11, and 20 to 23. deepseek-harness covers 1 to 8 and 10 to 14 and 16 to 21. Reading a single system end to end is therefore not the intended path; the layers are.

How the Material Is Meant to Be Used

The README gives three instructions, and they are more specific than the usual read-the-docs advice. Read the sections in order, because each builds on the layer before it. For a runnable section, read src/loop.py first, then run its demo.py. Then diff that section's src/ against the section before it, because the diff is the one mechanism the section adds.

That third instruction is the actual method. If section 2 introduces the tool runtime, the delta between section 1's src/ and section 2's src/ is the registry, schemas, and dispatch that the tool runtime section describes. Learning by diff means you never have to trust a prose summary of what changed; the change is in the tree. It also means the repository only works if the sections really are cumulative, which is a structural promise you can check in a few minutes by listing the src/ directories.

The repository structure is not spelled out in the excerpt beyond section folders such as sections/01-agent-loop/ and sections/02-tool-runtime/, plus assets/ for the diagrams. The README references assets/the-agent-loop.png and assets/learning-path.png. Whether every section ships a runnable demo is not confirmed by the material; the README says for a runnable section, which implies some are not. Treat the presence of demo.py per section as something to verify rather than assume.

Running the Demos: What the README Actually Specifies

The commands in the README are minimal, and it is worth being honest about that. It names python as the language, points at src/loop.py and demo.py inside each runnable section, and links a Running the demos anchor in the contents list. It does not give a package manager invocation, a dependency file, an environment variable, or a configuration key in the portion available here.

So the concrete instruction you can act on is a path, not a command line: open sections/01-agent-loop/src/loop.py, read it, then run the section's demo.py. Because the sections build on each other, run them in numeric order rather than jumping to the layer you care about; the diff method depends on having the previous section in hand. If a section has no demo.py, the README's own phrasing says it is a reading section, and you should treat it as prose plus a diff target.

One expectation to set before you start: these demos exercise a loop, and a loop calls a model. Nothing in the README excerpt states which provider, key, or endpoint the demos use, or whether any section runs offline against a stub. That is the first thing to check in the source before you plan an afternoon around it. If the demos need a live model call, the cost and the setup are yours, and the repository does not appear to abstract that away.

Where the Approach Gets Thin

The failure modes are a section of the curriculum, not a section of this review, but the repository has limits of its own. The strongest is the version pin. Claude Code v2.1.88, Hermes Agent v2026.7.1, mini-swe-agent v2.4.5, and dsh-v0.1.0-rc.7 are snapshots. A section that explains how a permission mode is implemented is a description of that build, and the README does not describe a process for tracking upstream changes. If your team runs a different version, the mechanism may still be conceptually right and concretely wrong.

The second limit is the reading model itself. Diffing src/ between sections teaches the increment well, but it assumes the sections are small enough to diff by eye and honest enough that the diff is the whole story. Where a layer is mostly configuration or policy rather than code, the diff will look trivial while the design is not. The README's own framing, that the loop is small and most engineering is around it, predicts this: the interesting parts of permissions and context management may not compress into a clean code delta.

The third is scope. This is not a library, a CLI, or a benchmark. It has no releases in the sense of installable artifacts; the recent tags are content milestones, including v1.6.0 renaming the project to learn-agent-architecture, v1.5.2 adding Japanese and Korean translations, and v1.5.1 refreshing the Chinese translation. If you arrived looking for a package to add to requirements.txt, you are in the wrong repository, and no amount of reading will change that.

mini-swe-agent as the Contrast Case

The README names mini-swe-agent as the research baseline: one bash tool, about 150 lines, read for the smallest complete loop plus budgets and the eval harness. That is the sharpest alternative in the material, and the difference is one of intent rather than feature count. mini-swe-agent is a minimal agent you can run and measure. This repository is a course about how agents like it, and larger ones, are assembled.

The practical consequence: if your goal is to produce numbers on a task suite, the baseline is the thing to run, and the sections here are background reading. If your goal is to decide how to structure permissions, hooks, and subagent boundaries in something you are building, the baseline gives you almost no guidance because it deliberately omits those layers. The repository's own section map reflects this. mini-swe-agent is studied in sections 0 to 3, 8, 10, 11, and 20 to 23, skipping the middle layers where the harness gets complicated, which is exactly the region a production harness lives in.

A second alternative sits inside the same family: deepseek-harness, where the README says even the loop is a replaceable plugin. If you want to see a harness designed for substitution rather than a harness designed to be read, that is the worked example to study, and the companion repo learn-deepseek-harness goes one plugin seam at a time. The difference from mini-swe-agent is stark. One minimizes the surface; the other makes every part of the surface a seam.

Licence, Translations, and What You Are Maintaining

The repository is MIT licensed, and the README carries an MIT badge linking to LICENSE. For a curriculum you read, copy snippets from, and diff against your own code, MIT is permissive and unsurprising. The caveat worth stating is that the licence covers this repository's text and code, not the four systems it studies. Claude Code, Hermes Agent, mini-swe-agent, and deepseek-harness carry their own licences, and reading a section here tells you nothing about what you may do with their source. Check each upstream project separately; this is not legal advice.

Maintenance cost falls mostly on the reader. The repository has no runtime dependency you must keep current, because it is not a package. What decays is accuracy against upstream versions, and the README does not promise a cadence for re-verifying the sections against new releases. The translation set (English, Traditional Chinese, Simplified Chinese, Japanese, Korean, with the Chinese refresh and the Japanese and Korean additions visible in the tags) adds a second drift axis: translations can lag the English text, and the tag history suggests they are updated in separate passes.

For a team, the honest accounting is that adopting this costs reading hours and a periodic re-check against the systems you actually use. It returns a vocabulary for harness decisions and a habit of diffing implementations instead of trusting summaries. That is a real return for engineers who already ship agent code. It is a poor return for anyone who wants a dependency, because there is nothing here to depend on.

Editorial conclusion

Adopt this if you already write agent code and want a structured way to read real harnesses, because the diff-your-own-src method forces you to name the mechanism each layer adds. Skip it if you need a library to import, a hosted service, or an evaluation leaderboard; this repository teaches and points elsewhere for those. Before committing time, open sections/01-agent-loop/, confirm src/loop.py and demo.py exist and run on your Python version, and check the stated version studied for each system against the version you actually use, since the writeups are pinned to specific releases such as Claude Code v2.1.88 and mini-swe-agent v2.4.5.

Official sources

1. hardness1020/learn-agent-architecture on GitHub
2. Issues
3. License: MIT
4. README
5. Releases