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.

Stars
★ 352
Last updated
4d ago
License
MIT
Primary language
HTML

At a glance

How it runs
Library / SDK
Works with
Universal · cross-platform
Cost
Free, no paid service needed
Setup effort
Low · running in minutes
You'll need
PythonpytestShell / CLILocal filesystem
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.

  1. An architect designing an agent system needs to locate a failure mode at a matrix coordinate and pick the right pattern
  2. An engineer implementing a pattern (e.g. Generator-Critic, Hierarchical Delegation) wants a minimal runnable reference plus invariant tests
  3. A team wants to check whether its implementation matches how production harnesses like Claude Code, Aider, or OpenHands actually do it
  4. A reader following *Designing AI Agents* or the Geektime column wants accompanying executable code
  5. 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
pytest

example.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?

Pros
  • 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
Limitations
  • 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?

FollowAgents source review · FARS-2.1
Some gaps
72/ 100 5-point scale 3.6 / 5
Trust 17/29
Reliability 8/14
Adaptability 15/18
Convention 14/18
Effectiveness 12/13
Verifiability 6/8
Why each dimension lost points
Trust17 / 29 · 2.9/5

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.

Reliability8 / 14 · 2.9/5

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.

Adaptability15 / 18 · 4.2/5

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.

Convention14 / 18 · 3.9/5

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.

Effectiveness12 / 13 · 4.6/5

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.

Verifiability6 / 8 · 3.8/5

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.

Risks and how to mitigate them
  • 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.
Evidence confidence: Low Reviewed Nov 21, 2026 Reviewed revision 7dba9d05cef5
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/agent-design-patterns.svg)](https://followagents.com/en/agents/agent-design-patterns)
<a href="https://followagents.com/en/agents/agent-design-patterns"><img src="https://followagents.com/badge/agent-design-patterns.svg" alt="FARS review"></a>

FAQ

Do I need an LLM API key?
No. The repo states every example.py "runs without API keys". Upstream projects (Claude Code, Aider, etc.) are cited in documentation only — nothing to install or pay for.
Is this a framework or a library?
Neither, strictly. It is a pattern catalog plus reference implementations; the README is explicit that it is "Not a framework" and points to LangGraph, agno, DeerFlow, or OpenHands for production runtimes.
Do all patterns have code?
Most matrix cells have runnable code (✅); a few are scaffolded (🟡), such as Skill Package, Self-Heal Loop, and Experience Replay. Each pattern.py is a 50–250 line minimal honest implementation.
How can I contribute?
Four contribution types are especially welcome: citation drift (upstream file/line no longer matches), invariant violations, new language ports (TypeScript/Go as separate top-level folders), and new engineering slices. New patterns: open an issue first to discuss matrix placement.
Where is the full evolving case study code?
The chapter-by-chapter evolving Argus codebase lives in the companion repo huangjia2019/designing-ai-agents; this repo is the standalone pattern catalog and also includes composition/c-argus-full-case/.
Is Agent Design Patterns (ADPS) free?
Yes. Agent Design Patterns (ADPS) is free to use and does not need a paid service.
Is Agent Design Patterns (ADPS) open source?
Yes. The source code is on GitHub (huangjia2019/agent-design-patterns) under the MIT licence.
Is Agent Design Patterns (ADPS) safe to use?
FollowAgents' FARS review (Nov 21, 2026) scored Agent Design Patterns (ADPS) 17/29 on trust and safety. None of the eight safety controls the review checks for was missing outright.
Is Agent Design Patterns (ADPS) still maintained?
Yes. The latest commit on GitHub is from 2026-11-18, within the last 30 days.
Who makes Agent Design Patterns (ADPS)?
Agent Design Patterns (ADPS) is published on GitHub by the account huangjia2019. FollowAgents has not verified which person or company is behind that account.
Was this page helpful?
View on GitHub ↗ Install ↓

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related concepts