Agent Design Patterns

Reference code and editable ADPS documentation for agent architecture: 27 core patterns, extension patterns, and three cross-cutting engineering concerns.

English documents · 中文文档 · Review and publishing

Code and documentation now share this repository. Propose article changes through a PR, or comment on a passage on the website. Accepted source revisions are published separately; each website article links to the exact source commit it displays.

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

📖 Browse the full pattern documentation — every pattern with its whitepaper, organized by cognitive function, with a left-rail index: adpsagent.com/zh/patterns. Enterprise case studies (蓝皮书) live at adpsagent.com/zh/cases.

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 ↳ chain · route · parallel · loop · hierarchy · orchestrate

The current public framework places 27 core patterns in the seven-by-six matrix. Observability, Evaluation & Validation, and Security & Identity are cross-cutting concerns. The book and older examples may use earlier catalogue versions; the current pattern documentation records the public definitions and historical entries.

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.

X1 Observability retains the existing Observability Harness code. Its folder is not moved, so older book and course links continue to work. See also X2 Evaluation & Validation and X3 Security & Identity.

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

Empty cells do not establish an industry gap. A pattern may have several implementations; the matrix records its primary coordinate.

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.

Collaboration bonus: asyncio.gather or a multi-agent Harness can put outputs in one list; it cannot define when that list earns a business conclusion. Run lightweight workbench B1 for bank timeout, duplicate lineage, unit mismatch, and the case where all workers succeed while the business release is correctly denied.

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.