Learn how modern AI agents are built around the LLM.

English · 繁體中文 · 简体中文

The model reasons. The harness gives it action, state, and limits: it runs tools, keeps state across calls, gates side effects, and coordinates loops, none of which a model call does 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.

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

Each system is a worked example for the sections below.

More systems can be added later, including Hermes Agent, OpenClaw, aider, and mini-swe-agent.

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

flowchart LR
    U([User intent]) --> M["messages[]"]
    M --> L{{LLM}}
    L -->|stop_reason: tool_use| T[Tool runtime]
    T --> P{Permitted?}
    P -->|deny / ask| M
    P -->|allow| X[Execute tool]
    X --> R[Tool result] --> M
    L -->|stop_reason: end_turn| D([Reply to user])

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

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 test.py and demo.py.
• Diff a section's src/ against the section before it. The diff is the one mechanism that section adds.

Seven layers, from the basic loop to a multi-agent harness. Each row links to one self-contained writeup.

All 21 section writeups are present, from 00-harness-thesis/ through 20-observability/.

awesome-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
│   └── 20-observability/
├── systems/                   # per-system deep dives
├── patterns/                  # shared patterns and failure modes
└── references/                # primary sources and prior art

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

Sections 1 to 20 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.

Sections 1 to 20 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

• 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.