hardness1020/learn-agent-architecture

What it solves

AI models are capable of reasoning, but they cannot perform actions, maintain state, or manage workflows on their own. This project demystifies the "harness"—the essential software infrastructure that wraps around an LLM to turn it into a functional, autonomous agent capable of executing tools, managing memory, and coordinating complex tasks.

How it works

The repository breaks down agent architecture into 24 progressive, self-contained sections. Each section follows a consistent structure: defining the problem, explaining the mechanism, showing how real-world systems implement it, and identifying common failure modes. The code is cumulative; you can run the provided demos and compare the differences between sections to see exactly how each new layer of functionality is added to the agent's loop.

Who it’s for

This is for developers and engineers who want to understand the mechanics of modern AI agents. Whether you are building your own agent or trying to understand how existing systems like Claude Code or SWE-agent function, this repository provides a clear, code-first roadmap to mastering agent design.

Highlights

• Cumulative Learning: Each section builds on the previous one, allowing you to see how simple loops evolve into complex, autonomous systems.
• Real-World Examples: Studies popular agent frameworks like Claude Code, Hermes Agent, and deepseek-harness to ground theoretical concepts in production-grade code.
• Runnable Demos: Every section includes a src/ folder with code that can be run locally to observe the agent's behavior in real-time.
• Comprehensive Scope: Covers everything from basic tool execution and permission gating to advanced topics like subagents, memory subsystems, and graph-based control flow.