Purpose
awesome-agent-architecture is an open-source repository for learning AI agent architecture from scratch. It explains how modern AI agents are built around LLMs, with the core idea being: the model is responsible for reasoning, while the harness (execution framework) turns reasoning into controlled actions—running tools, maintaining state across calls, gating side effects, and coordinating loops, which a single model call itself cannot do.
Main Capabilities
The repository explains the harness section by section by layer: loop, tools, memory, permissions, context, tasks, interfaces. Each section is self-contained and organized using a unified four-part perspective: problem, mechanism, implementation in real systems, failure modes.
The repository contains 24 section documents from 00-harness-thesis/ to 23-evaluation/, with each section directory named NN-name/ and containing a README.md. Sections 1 through 23 also come with runnable src/, and the code accumulates section by section, with each section adding one mechanism and evolving loop.py, so the diff between adjacent sections intuitively shows the changes.
The research systems include: claude-code (used for mechanism naming and implementation paths), hermes-agent, mini-swe-agent, deepseek-harness, all of which are open-source (MIT) or backup-nature research subjects.
How to Use
The repository's suggested learning path: read the sections in order, with each section building on the previous layer; for runnable sections, first read src/loop.py, then run its demo.py; compare a section's src/ with the previous section, and the diff is the mechanism newly added in that section.
Running the demos: Sections 1 through 23 provide runnable demos, configured all at once from the repository root. Locked dependencies are written in requirements.txt; .env is ignored by git and contains ANTHROPIC_API_KEY, optional ANTHROPIC_MODEL, and optional ANTHROPIC_BASE_URL. Each runnable section contains test.py (offline checks, no key required) and demo.py (live demo against the API).
Applicable Scenarios
Suitable for those who want to systematically understandthe differences between coding tools, chat assistants, and autonomous runners, because the main difference among these three lies in the choice of harness. It is also suitable for contributors who want to add system cases according to a unified structure, deepen the mechanism of a certain section, or submit sourced correctness fixes.
Companions and In-Depth Material
Three companion repositories provide more in-depth content: learn-agent-memory extends the memory loop into a production-grade memory subsystem; learn-deepseek-harness learns deepseek-harness from scratch, plugin seam by plugin seam; EvalGrill turns real cases of agent applications into reproducible, verifiable evaluation sets.
Limitations
The statements in the repository documentation are reconstructions from source code, documentation, and behavior, and sourced corrections are welcome. Some content depends on an Anthropic API key to run live demos. The repository does not provide information in the materials about fees, pricing, platform compatibility, etc., and none is currently provided.
