Agent Design Patterns

A 7×6 framework for agent architecture. 28 patterns, each placed at a coordinate, each with runnable code and a verified engineering slice from real production codebases.

The model spends. The harness budgets. This repo is the vocabulary you can put in your project tomorrow.

简体中文 README · Manning · Designing AI Agents · Paper · arXiv:2605.13850 · 极客时间专栏 · Newsletter · Author site

Looking for the full Argus running example as one evolving
codebase, organized by book chapter? See the companion repo
huangjia2019/designing-ai-agents
— Argus grows module by module from Ch2 to Ch10, with each chapter's
patterns/ + argus/ side by side. That repo follows the book's
narrative; this repo is the standalone pattern catalog.

The book

Designing AI Agents — the design-pattern catalogue for production AI agents. (Manning)

The framework comes from a paper

The two-axis framework, the 27 named patterns, and the five
pattern-selection laws are introduced in A Two-Dimensional Framework
for AI Agent Design Patterns: Cognitive Function × Execution
Topology (Huang & Zhou,
arXiv:2605.13850). This repository is the runnable companion to the
paper.

Why this exists

Most "agent architecture" guides give you a flat list — Reflection, ReAct,
Multi-Agent, Tree of Thoughts, Reflexive Metacognitive, and so on. A flat
list answers what patterns exist. It does not answer where my problem
sits, and which pattern lives at that coordinate.

A loan-evaluation agent crashes not because Reflection is missing but
because Perception-stage budget allocation dropped the disqualifying
document. A multi-agent code reviewer drifts not because ReAct is wrong
but because two Reflection critics contradict each other and there is no
governance gate to resolve it. These are not different patterns — they
are patterns sitting at specific coordinates in a structured design
space. Without the coordinates you can't see them.

This repo gives you the coordinates.

The two-axis framework

Every agent pattern sits at the intersection of two orthogonal axes.

• Cognitive function — what the agent is doing
  ↳ perceive · remember · reason · act · reflect · collaborate · govern
• Execution topology — how the work is laid out at runtime
  ↳ single-step · sequential · parallel · loop · router · hierarchy

Seven × six = 42 cells. The 28 cells where interesting patterns live are
the chapters of Designing AI Agents (Manning) and the lectures of the
极客时间 column.

The framework's claim is not that everything fits the matrix. The claim
is that giving a pattern a coordinate forces an answer to "why is this
pattern here and not somewhere else". A flat list lets you skip the
question. A matrix does not.

The matrix — click into any pattern

Every pattern below lives at one coordinate. Click any pattern name to
enter that folder's code and README. Cells marked ✅ have runnable code;
cells marked 🟡 are scaffolded.

Composition (putting patterns together):
Pattern Selection Card ·
Six-Step Methodology ·
Argus Full Case Study ·
Checklist Benchmark Case

The 14 empty cells mark either industry gaps no production harness has
filled yet, or topology-function combinations whose patterns haven't
crystallized.

Each pattern folder follows the same shape: pattern.py (the minimal
honest reference, 50–250 lines), example.py (a real-scenario case that
runs without API keys), test_pattern.py (the invariants the pattern
must hold), and bilingual README.md / README.zh-CN.md.

Engineering slices — verified, not hallucinated

Every pattern's README cites real production code. Citations are
file-and-line in upstream open-source projects, verified at the time of
writing. If you find a citation that no longer matches the upstream code,
open an issue — that's a bug, not a documentation choice.

The eight production harnesses the framework tracks: Claude Code,
Codex CLI, Aider, OpenCode, OpenClaw, Hermes Agent, DeepAgents, DeerFlow,
OpenHands. Each pattern's README pulls from at least one of these to
show the pattern in real production form, not toy form.

What this repo is not

• Not a framework. Use LangGraph,
  agno,
  DeerFlow, or
  OpenHands for a production
  runtime. This repo is the design vocabulary you apply on top of any of
  them. Switching frameworks does not change the matrix.
• Not a flat catalog. A list answers what patterns exist. The matrix
  answers where a problem sits and which patterns are wrong for that
  position.
• Not toy code. Every pattern.py is small (50–250 lines) on
  purpose, but it is honest code with real invariants and tests. Each
  example.py runs on data shaped like production. Engineering slices
  in the READMEs cite verified upstream files.

Quickstart

git clone https://github.com/huangjia2019/agent-design-patterns.git
cd agent-design-patterns
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Run a pattern's case
python perception/a-context-triage/example.py
python perception/b-semantic-compaction/example.py

# Run all invariant tests
pytest

Each pattern folder is self-contained. No central framework, no plugin
system to learn. Read the folder's README, look at pattern.py, run
example.py, read the tests.

How to read a pattern folder

<pattern-folder>/
  README.md                # The why — what failure mode this pattern catches
  README.zh-CN.md          # 中文版
  pattern.py               # The minimal honest implementation
  example.py               # A runnable case on production-shaped data
  test_pattern.py          # The invariants the pattern must hold

Read the README first — it's the why and the upstream slice. Then read
pattern.py to see the smallest amount of code that solves it. Run
example.py to see it work on data with shape. Tests pin the invariants
you must not break when adapting.

The thesis behind the framework

Three lines from the book:

• Designing an agent is solving a constrained allocation problem.
• A fixed token budget must be distributed across competing cognitive
  demands under non-deterministic execution paths.
• The model is the spender. The harness is the budgeter. The patterns
  are the strategies.

Every pattern in the matrix is a strategy for one of those three roles —
how the harness budgets, how the patterns allocate, how the model is
positioned to spend. The matrix is what makes the strategies discussable
as a system rather than as a flat list.

Book · Column · Newsletter

The book gives you the theory. The column gives you the lectures. This
repo gives you runnable code.

Author

Jia Huang (黄佳) — Lead Research Engineer at A*STAR
Singapore, formerly senior consultant at Accenture Singapore.
Twenty years across NLP, LLMs, and AI applications in MedTech and
FinTech. Author of two forthcoming English-language books (Designing AI
Agents with Manning, RAG from First Principles with Packt) and six
Chinese-language books on machine learning, GPT, AI agents, RAG, and
data analysis with cumulative readers in the hundreds of thousands.

The two-axis framework is the author's original contribution; the
constituent elements (seven cognitive functions, six execution
topologies) are not new — the contribution is the orthogonal organization.

kage-ai.com · LinkedIn · Substack · [email protected]

Contributing

Issues welcome. Particularly useful:

• Citation drift — a verified engineering slice in a README points at
  a file or line that no longer matches upstream
• Invariant violations — a test misses a case that you've seen the
  pattern fail in production
• New language ports — TypeScript / Go ports of any pattern, opened
  as a separate top-level folder
• New engineering slices — a production harness you've worked with
  shows the pattern in a form not yet documented in the README

Pull requests for new patterns: please open an issue first to discuss
where the pattern sits in the matrix.

Citation

If this framework is useful in your work, please cite the paper:

@misc{huang_zhou_2026_dual_axis,
  author        = {Huang, Jia and Zhou, Joey Tianyi},
  title         = {A Two-Dimensional Framework for AI Agent Design Patterns:
                   Cognitive Function and Execution Topology},
  year          = {2026},
  eprint        = {2605.13850},
  archivePrefix = {arXiv},
  primaryClass  = {cs.AI},
  doi           = {10.5281/zenodo.19036557},
  url           = {https://arxiv.org/abs/2605.13850}
}

License

MIT. See LICENSE.