Learn Agent Architecture

Learn how modern AI agents are built around the LLM.

English · 繁體中文 · 简体中文 · 日本語 · 한국어

The model reasons. The harness turns that reasoning into controlled action: it runs tools, keeps state across calls, gates side effects, and coordinates loops. A model call cannot do any of those things by itself.

This repo explains the harness section by section: loop, tools, memory, permissions, context, tasks, and interfaces. Learn it once and you can read many agents, since a coding tool, chat assistant, and autonomous runner mostly differ in harness choices.

Three companion repos go deeper than one section can:

• learn-agent-memory: scales the memory loop into a production memory subsystem.
• learn-deepseek-harness: learns deepseek-harness from scratch, one plugin seam at a time.
• EvalGrill: turns real cases from agent applications into reproducible, verifiable eval sets.

Contents: Loop · Method · Systems · Sections · Structure · Running

---

The Agent Loop

Most agents share the same control flow: call the model, run requested tools, append results, and call the model again.

The loop is small. Most engineering is around it: dispatch tools, gate side effects, manage context, persist state, and coordinate other loops.

---

How to learn

Every section is self-contained and uses the same four-part lens:

1. Opening. What problem this layer solves.
2. Mechanism. The general design and control flow.
3. Per system. How real systems implement it.
4. Failure modes. What breaks and how to mitigate it.

To learn from this repo:

• Read the sections in order. Each builds on the layer before it.
• For a runnable section, read src/loop.py, then run its demo.py.
• Diff a section's src/ against the section before it. The diff is the one mechanism that section adds.

---

Systems Under Study

Each system is a worked example for the sections below.

More systems can be added later, including OpenClaw and aider. Two companion repos go deeper: learn-agent-memory for the memory layer, and learn-deepseek-harness for learning deepseek-harness from scratch.

---

Sections

Eight layers, from the basic loop to a harness that runs itself. Each row links to one self-contained writeup.

Section 9 continues in learn-agent-memory: ten more stages that scale its memory loop to production.

---

Repository Structure

All 24 section writeups are present, from 00-harness-thesis/ through 23-evaluation/.

learn-agent-architecture/
├── README.md                  # top-level map
├── sections/                  # one folder per section
│   ├── 00-harness-thesis/     # README.md per section
│   ├── 01-agent-loop/src/     # runnable chain starts here
│   ├── ...
│   └── 23-evaluation/
└── references/                # primary sources and prior art

Each section folder is NN-name/ and contains a README.md.

Sections 1 to 23 also carry a runnable src/. The code accumulates section by section. Each section adds one mechanism and evolves loop.py, so a diff between adjacent sections shows what changed.

Deep dives that outgrow one section live in their own repos. learn-agent-memory scales the section 9 loop into a full memory subsystem. learn-deepseek-harness learns deepseek-harness from scratch, one plugin seam at a time.

---

Running the Demos

Sections 1 to 23 ship runnable demos. Set up once from the repo root:

uv venv
uv pip install -r requirements.txt
cp .env.example .env        # then add your ANTHROPIC_API_KEY

Pinned dependencies are in requirements.txt. .env is gitignored and holds:

• ANTHROPIC_API_KEY
• optional ANTHROPIC_MODEL
• optional ANTHROPIC_BASE_URL

Each runnable section has:

• test.py: offline checks, no key needed.
• demo.py: live demo against the API.

python sections/01-agent-loop/src/test.py         # offline
uv run python sections/01-agent-loop/src/demo.py  # live

---

Contributing

• Add a system. Slot a new agent into the same section structure.
• Deepen a section. Add a mechanism, clearer diagram, or sharper failure mode.
• Correct the record. These are reconstructions from source, docs, and behavior. Sourced corrections are welcome.

Favor named, verifiable mechanisms over speculation. Cite sources. See CONTRIBUTING.md for the full PR checklist.

---

References

• claude-code: Claude Code source backup used for mechanism names and implementation paths.
• hermes-agent: Open-source agent harness (MIT) used as the second system under study.
• mini-swe-agent: Minimal SWE agent (MIT) used as the third system under study.
• deepseek-harness: Plugin-based agent harness (MIT) used as the fourth system under study.
• learn-claude-code: Code-first harness reconstruction and section framing.
• EvalGrill: companion tool (Apache-2.0) that applies section 23, building eval sets from real agent-application cases.
• Anthropic Agent Skills best practices: Progressive disclosure levels for skills.
• Anthropic prompt caching: Cache breakpoints, TTLs, pricing, and token minimums.
• cobusgreyling/loop-engineering: Loop building blocks and readiness levels.
• LangChain · The art of loop engineering: The four stacked loops.
• Addy Osmani · Loop engineering: Composed building blocks for agent loops.
• MindStudio · What is loop engineering: Goal conditions for autonomous workflows.
• Lilian Weng · Harness engineering for self-improvement: The improvement loop, with gates outside the loop.
• LangChain · 3 years of graph engineering: Nodes, edges, cycles, and agents as nodes.
• Anthropic · Building effective agents: Workflows vs agents and the five workflow shapes.
• Google · Why we built ADK 2.0: Routing in code and context isolation between nodes.
• TypeSafe Jev docs: the request contract and answer shape of a typed decision model. Section 22 wires one into a graph edge in decide.py.
• ai-agent-book: 《深入理解 AI Agent》 by 李博杰 (Apache-2.0). Chapter 6 grounds the evaluation section.

---

Acknowledgements

Thanks to these collections for listing this project:

• walkinglabs/awesome-harness-engineering
• Jenqyang/Awesome-AI-Agents
• WenyuChiou/awesome-agentic-ai-zh