Agent Design Patterns (ADPS)
A 7×6 two-axis matrix framework that places 27 agent design patterns at cognitive-function × execution-topology coordinates, each with runnable Python code.
- Source repo
- huangjia2019/agent-design-patterns
- Stars
- ★ 352
- Last updated
- 4d ago
- License
- MIT
- Primary language
- HTML
- FA score
- 72/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platform
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- An architect designing an agent system needs to locate a failure mode at a matrix coordinate and pick the right pattern
- Not a fit if
- Teams seeking a production runtime framework — it is explicitly not one; use LangGraph/OpenHands etc.
- Developers wanting a ready-to-run agent product rather than design reference material
- Maintenance
- Commits in the last 30 dayslast commit 2026-11-18
- Source review
- 72/100 · Some gaps
What does this agent do, and when should you use it?
This is the companion codebase to Jia Huang's book *Designing AI Agents* (Manning) and the arXiv paper on a two-dimensional framework, organizing agent patterns as "cognitive function (perceive/remember/reason/act/reflect/collaborate/govern) × execution topology (chain/route/parallel/loop/hierarchy/orchestrate)". Each pattern gets a self-contained folder: a 50–250 line pattern.py, an example.py that runs without API keys, a test_pattern.py pinning invariants, and bilingual READMEs. The matrix includes cross-cutting concerns: Observability, Evaluation & Validation, and Security & Identity. Each pattern's README cites verified file-and-line engineering slices from upstream projects such as Claude Code, Aider, OpenHands, and DeerFlow. MIT licensed, code and documentation share the repo, and accepted revisions are published with their exact source commit.
Provides 27 core patterns in the 7×6 matrix (e.g. Context Triage, Semantic Compaction, RAG, Chain of Thought, Plan & Execute, Approval Gate), each in a folder with pattern.py (minimal honest implementation), example.py (runnable case on production-shaped data), test_pattern.py (invariant tests), and bilingual READMEs. Most cells are runnable (✅); a few are scaffolded (🟡). A composition/ directory supplies combination methods: Pattern Selection Card, Six-Step Methodology, the Argus full case study, and a Checklist Benchmark case. READMEs cite verified upstream slices such as Aider's RepoMap, Claude Code's 4-layer memory, OpenHands' condenser_config, and DeerFlow's schema-driven triage. Workflow: git clone, pip install -e '.[dev]', run any example.py, and run pytest for all invariant tests.
- An architect designing an agent system needs to locate a failure mode at a matrix coordinate and pick the right pattern
- An engineer implementing a pattern (e.g. Generator-Critic, Hierarchical Delegation) wants a minimal runnable reference plus invariant tests
- A team wants to check whether its implementation matches how production harnesses like Claude Code, Aider, or OpenHands actually do it
- A reader following *Designing AI Agents* or the Geektime column wants accompanying executable code
- A writer or translator wants to revise pattern whitepapers via PR or read the same pattern in English and Chinese
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Install / run
pip install -e ".[dev]"
How do you install or deploy this agent?
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]"How do you use this agent?
Each pattern folder is self-contained. Read the folder's README first (the why and the upstream slice), then pattern.py, then run the case:
python perception/a-context-triage/example.py
python perception/b-semantic-compaction/example.py
# Run all invariant tests
pytestexample.py runs without API keys; test_pattern.py pins the invariants you must not break when adapting.
What are this agent's strengths and limitations?
- The two-axis matrix forces an answer to "why is this pattern here and not somewhere else", unlike flat pattern lists
- Each README cites file-and-line upstream production slices, and citation drift is treated as a bug via issues
- Every example.py runs without API keys and test_pattern.py pins invariants, making adaptation safe and verifiable
- Not a runtime framework — the README explicitly recommends LangGraph, agno, DeerFlow, or OpenHands for production
- Some patterns are scaffolded only (🟡: Skill Package, Self-Heal Loop, Experience Replay) without full runnable code
- The book and older examples may use earlier catalogue versions; pattern counts differ (README says 27, repo description says 28), so the current pattern documentation is authoritative
How does this agent compare with similar options?
The README positions itself against runtime frameworks LangGraph, agno, DeerFlow, and OpenHands: those are production runtimes, while this repo is the design vocabulary you apply on top of any of them — "switching frameworks does not change the matrix".
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Agent Design Patterns (ADPS) This agent | 72 · Some gaps | Library / SDKFree | ★ 352 | 4d ago | HTML | — |
| PowerContext | 82 · Good | CLIFree | ★ 1.8k | today | Python | Codex · Claude Code |
| CaveAgent | 63 · Some gaps | Library / SDKFree + model costs | ★ 225 | 2mo ago | Python | OpenAI API · Claude API |
| Hello-Agents | 53 · Major gaps | Web appFree + model costs | ★ 88k | 9d ago | Python | OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
Zero runtime dependencies and keyless offline examples indicate a low-privilege, low-external-effect design; the README explicitly positions the repo as reference code, not a production runtime. Deducted because the actual pattern.py/example.py bodies are not in this packet, so least_privilege, sensitive-data handling, and rollback paths cannot be verified from source; user_confirmation/rollback/sensitive_data_handling scored on assertion alone. Source attribution is excellent: MIT license, named author, arXiv citation, and a citation-drift issue process.
CI (Python 3.11/3.12 matrix) runs every listed example and pytest, with range-pinned dependencies — good availability evidence. Deducted for self-consistency defects: the external description says 28 patterns while the README repeatedly says 27, and the 'eight production harnesses' list actually names nine. Failure-message quality depends on unseen source, scored 1.
Audience and scenario are clearly defined (design vocabulary and learning reference, not a runtime), and the 'What this repo is not' section is strong boundary evidence. Deducted for environment fit: only >=3.11 and offline examples are promised, with no Windows/container guidance; pattern selection is documented via a matrix rather than any executable mechanism.
Information architecture is the repo's strongest area: the 7×6 matrix, uniform folder shape (pattern.py/example.py/test_pattern.py/bilingual README), quickstart, bilingual docs, and separately licensed publication text all reach full marks. Deducted for absent CHANGELOG and a static 0.1.0 version; letter-prefixed folder names (a-, b-) are reorder-sensitive despite 'folder not moved' compatibility notes; maintenance rests on an individual's issue process with no governance statement.
Compared with flat pattern lists, the coordinate framework plus runnable slices plus production citations has clear marginal value; zero core dependencies and self-contained folders keep adoption cost low. Deducted for output usability: pattern.py quality is unobserved in this packet and 🟡 scaffolded cells are not yet runnable.
Engineering slices cite file-and-line upstream locations and are declared 'verified, not hallucinated', with an issue path for citation drift — traceability at full marks. Deducted because those verification claims cannot be cross-checked in this static packet (several citations point to 2026-dated arXiv IDs/events outside a checkable window), and fact-versus-inference separation is left to the reader.
- The static packet contains no pattern.py or test_pattern.py bodies; least privilege, error handling, and test quality cannot be verified and rest on README assertions alone — low confidence.
- Pattern-count self-inconsistency: the description says 28 patterns while the README says 27, and the 'eight production harnesses' list names nine; verify before citing.
- Some citations reference 2026-dated arXiv IDs and upstream file/line numbers that are highly drift-prone; validate each citation before reuse.
- The four 🟡-marked patterns are scaffolds only; the optional langgraph/claude-agent-sdk extras pull recent dependencies that warrant a separate security audit before production use.
- Publication text and third-party media carry separate license terms (docs/publications/LICENSE.md); read them before republication rather than assuming blanket MIT.
FAQ
Do I need an LLM API key?
Is this a framework or a library?
Do all patterns have code?
How can I contribute?
Where is the full evolving case study code?
Is Agent Design Patterns (ADPS) free?
Is Agent Design Patterns (ADPS) open source?
Is Agent Design Patterns (ADPS) safe to use?
Is Agent Design Patterns (ADPS) still maintained?
Who makes Agent Design Patterns (ADPS)?
Thanks — we use this to improve the page.