[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-83287":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":15,"stars30d":15,"stars90d":14,"forks30d":14,"starsTrendScore":12,"compositeScore":16,"rankGlobal":9,"rankLanguage":9,"license":17,"archived":18,"fork":18,"defaultBranch":19,"hasWiki":20,"hasPages":18,"topics":21,"createdAt":9,"pushedAt":9,"updatedAt":37,"readmeContent":38,"aiSummary":9,"trendingCount":14,"starSnapshotCount":14,"syncStatus":13,"lastSyncTime":39,"discoverSource":40},83287,"agent-design-patterns","huangjia2019\u002Fagent-design-patterns","huangjia2019","A 7×6 framework for agent architecture. 28 patterns, each placed at a coordinate, runnable Python code with verified engineering slices from Claude Code, Aider, OpenHands, DeerFlow. Companion to Designing AI Agents (Manning) by Jia Huang.",null,"HTML",66,6,2,0,13,50.34,"MIT License",false,"main",true,[22,23,24,25,26,27,28,29,30,31,32,33,34,35,36],"agent","agent-architecture","agent-design","agent-framework","agent-patterns","agentic-architecture","agentic-design-patterns","agentic-workflows","ai-agent","ai-agents","context-engineering","design-patterns","harness","llm-agents","multi-agent","2026-06-12 04:01:40","# Agent Design Patterns\n\n> **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.**\n\n*The model spends. The harness budgets. This repo is the vocabulary you can put in your project tomorrow.*\n\n[简体中文 README](README.zh-CN.md) · [**Manning · *Designing AI Agents***](https:\u002F\u002Fhubs.la\u002FQ04hCsH10) · [Paper · arXiv:2605.13850](https:\u002F\u002Farxiv.org\u002Fabs\u002F2605.13850) · [极客时间专栏](https:\u002F\u002Ftime.geekbang.org\u002F) · [Newsletter](https:\u002F\u002Fagentpatterns.substack.com) · [Author site](https:\u002F\u002Fkage-ai.com)\n\n> **Looking for the full Argus running example as one evolving\n> codebase, organized by book chapter?** See the companion repo\n> [**huangjia2019\u002Fdesigning-ai-agents**](https:\u002F\u002Fgithub.com\u002Fhuangjia2019\u002Fdesigning-ai-agents)\n> — Argus grows module by module from Ch2 to Ch10, with each chapter's\n> `patterns\u002F` + `argus\u002F` side by side. That repo follows the book's\n> narrative; this repo is the standalone pattern catalog.\n\n---\n\n## The book\n\n\u003Ca href=\"https:\u002F\u002Fhubs.la\u002FQ04hCsH10\">\n  \u003Cimg src=\".\u002Fdocs\u002Fmanning-book-card.png\" alt=\"Designing AI Agents — Manning\" width=\"420\">\n\u003C\u002Fa>\n\n**[*Designing AI Agents*](https:\u002F\u002Fhubs.la\u002FQ04hCsH10)** — the design-pattern catalogue for production AI agents. (Manning)\n\n---\n\n## The framework comes from a paper\n\n[![A Two-Dimensional Framework for AI Agent Design Patterns — arXiv:2605.13850](.\u002Fdocs\u002Fpaper-card.png)](https:\u002F\u002Farxiv.org\u002Fabs\u002F2605.13850)\n\nThe two-axis framework, the 27 named patterns, and the five\npattern-selection laws are introduced in **[A Two-Dimensional Framework\nfor AI Agent Design Patterns: Cognitive Function × Execution\nTopology](https:\u002F\u002Farxiv.org\u002Fabs\u002F2605.13850)** (Huang & Zhou,\narXiv:2605.13850). This repository is the runnable companion to the\npaper.\n\n---\n\n## Why this exists\n\nMost \"agent architecture\" guides give you a flat list — Reflection, ReAct,\nMulti-Agent, Tree of Thoughts, Reflexive Metacognitive, and so on. A flat\nlist answers *what patterns exist*. It does not answer *where my problem\nsits, and which pattern lives at that coordinate*.\n\nA loan-evaluation agent crashes not because Reflection is missing but\nbecause Perception-stage budget allocation dropped the disqualifying\ndocument. A multi-agent code reviewer drifts not because ReAct is wrong\nbut because two Reflection critics contradict each other and there is no\ngovernance gate to resolve it. These are not different patterns — they\nare patterns sitting at *specific coordinates* in a structured design\nspace. Without the coordinates you can't see them.\n\nThis repo gives you the coordinates.\n\n---\n\n## The two-axis framework\n\nEvery agent pattern sits at the intersection of two orthogonal axes.\n\n* **Cognitive function** — *what the agent is doing*\n  ↳ perceive · remember · reason · act · reflect · collaborate · govern\n* **Execution topology** — *how the work is laid out at runtime*\n  ↳ single-step · sequential · parallel · loop · router · hierarchy\n\nSeven × six = 42 cells. The 28 cells where interesting patterns live are\nthe chapters of *Designing AI Agents* (Manning) and the lectures of the\n极客时间 column.\n\nThe framework's claim is not that everything fits the matrix. The claim\nis that **giving a pattern a coordinate forces an answer to \"why is this\npattern here and not somewhere else\"**. A flat list lets you skip the\nquestion. A matrix does not.\n\n---\n\n## The matrix — click into any pattern\n\n![Two-Axis Framework matrix: 7 cognitive functions × 6 execution topologies = 42 cells, 28 patterns](.\u002Fdocs\u002Fmatrix.png)\n\nEvery pattern below lives at one coordinate. Click any pattern name to\nenter that folder's code and README. Cells marked ✅ have runnable code;\ncells marked 🟡 are scaffolded.\n\n|  | **Chain** | **Parallel** | **Route** | **Loop** | **Orchestrate** | **Hierarchy** |\n|---|---|---|---|---|---|---|\n| **Perceive** | [Semantic Compaction ✅](.\u002Fperception\u002Fb-semantic-compaction\u002F) | [Multi-Modal Fusion ✅](.\u002Fperception\u002Fd-multimodal-fusion\u002F) | [Context Triage ✅](.\u002Fperception\u002Fa-context-triage\u002F) | — | [Progressive Discovery ✅](.\u002Fperception\u002Fc-progressive-discovery\u002F) | — |\n| **Remember** | [RAG ✅](.\u002Fmemory\u002Fb-rag\u002F) | — | [Hierarchical Retention ✅](.\u002Fmemory\u002Fa-hierarchical-retention\u002F) | [Failure Journals ✅](.\u002Fmemory\u002Fd-failure-journals\u002F) | [Progress Tracking ✅](.\u002Fmemory\u002Fc-progress-tracking\u002F) | — |\n| **Reason** | [Chain of Thought ✅](.\u002Freasoning\u002Fa-chain-of-thought\u002F) | [Parallel Exploration ✅](.\u002Freasoning\u002Fc-parallel-exploration\u002F) | [Complexity Routing ✅](.\u002Freasoning\u002Fb-complexity-routing\u002F) | [Iterative Hypothesis ✅](.\u002Freasoning\u002Fd-iterative-hypothesis\u002F) | — | — |\n| **Act** | [Prompt Chaining ✅](.\u002Faction\u002Fc-prompt-chaining\u002F) | — | [Tool Dispatch ✅](.\u002Faction\u002Fa-tool-dispatch\u002F) | — | [Plan & Execute ✅](.\u002Faction\u002Fb-plan-and-execute\u002F) | [Guardrail Sandwich ✅](.\u002Faction\u002Fd-guardrail-sandwich\u002F) |\n| **Reflect** | [Generator-Critic 🟡](.\u002Freflection\u002Fa-generator-critic\u002F) | — | [Skill Package 🟡](.\u002Freflection\u002Fb-skill-package\u002F) | [Self-Heal Loop 🟡](.\u002Freflection\u002Fd-self-heal-loop\u002F) | — | [Experience Replay 🟡](.\u002Freflection\u002Fc-experience-replay\u002F) |\n| **Collaborate** | [Handoff Chain 🟡](.\u002Fcollaboration\u002Fd-handoff-chain\u002F) | [Fan-out & Gather 🟡](.\u002Fcollaboration\u002Fb-fan-out-gather\u002F) | — | [Adversarial Review 🟡](.\u002Fcollaboration\u002Fc-adversarial-review\u002F) | — | [Hierarchical Delegation 🟡](.\u002Fcollaboration\u002Fa-hierarchical-delegation\u002F) |\n| **Govern** | — | [Progressive Commitment 🟡](.\u002Fgovernance\u002Fc-progressive-commitment\u002F) | [Approval Gate 🟡](.\u002Fgovernance\u002Fa-approval-gate\u002F) | — | [Observability Harness 🟡](.\u002Fgovernance\u002Fd-observability-harness\u002F) | [Blast Radius 🟡](.\u002Fgovernance\u002Fb-blast-radius\u002F) |\n\n**Composition** (putting patterns together):\n[Pattern Selection Card](.\u002Fcomposition\u002Fa-pattern-selection-card\u002F) ·\n[Six-Step Methodology](.\u002Fcomposition\u002Fb-six-step-methodology\u002F) ·\n[Argus Full Case Study](.\u002Fcomposition\u002Fc-argus-full-case\u002F) ·\n[Checklist Benchmark Case](.\u002Fcomposition\u002Fd-checklist-benchmark\u002F)\n\nThe 14 empty cells mark either industry gaps no production harness has\nfilled yet, or topology-function combinations whose patterns haven't\ncrystallized.\n\nEach pattern folder follows the same shape: `pattern.py` (the minimal\nhonest reference, 50–250 lines), `example.py` (a real-scenario case that\nruns without API keys), `test_pattern.py` (the invariants the pattern\nmust hold), and bilingual `README.md` \u002F `README.zh-CN.md`.\n\n---\n\n## Engineering slices — verified, not hallucinated\n\nEvery pattern's README cites real production code. Citations are\nfile-and-line in upstream open-source projects, verified at the time of\nwriting. If you find a citation that no longer matches the upstream code,\nopen an issue — that's a bug, not a documentation choice.\n\n| Pattern | Upstream slices cited |\n|---|---|\n| Context Triage | [Aider's RepoMap](https:\u002F\u002Fgithub.com\u002FAider-AI\u002Faider\u002Fblob\u002Fmain\u002Faider\u002Frepomap.py), [Claude Code memory hierarchy](https:\u002F\u002Fdocs.claude.com\u002Fen\u002Fdocs\u002Fclaude-code\u002Fmemory), [DeerFlow schema-driven triage](https:\u002F\u002Fgithub.com\u002Fbytedance\u002Fdeer-flow) |\n| Semantic Compaction | [OpenHands condenser_config](https:\u002F\u002Fgithub.com\u002FAll-Hands-AI\u002FOpenHands\u002Fblob\u002Fmain\u002Fopenhands\u002Fcore\u002Fconfig\u002Fcondenser_config.py), [Aider history.py](https:\u002F\u002Fgithub.com\u002FAider-AI\u002Faider\u002Fblob\u002Fmain\u002Faider\u002Fhistory.py), [Manus Context Engineering blog](https:\u002F\u002Fmanus.im\u002Fblog\u002FContext-Engineering-for-AI-Agents-Lessons-from-Building-Manus) |\n| Hierarchical Retention | [Claude Code 4-layer memory](https:\u002F\u002Fdocs.claude.com\u002Fen\u002Fdocs\u002Fclaude-code\u002Fmemory), [MemGPT virtual memory hierarchy (arxiv:2310.08560)](https:\u002F\u002Farxiv.org\u002Fabs\u002F2310.08560) |\n| RAG | [Anthropic Contextual Retrieval](https:\u002F\u002Fwww.anthropic.com\u002Fnews\u002Fcontextual-retrieval), [Reciprocal Rank Fusion (Cormack 2009)](https:\u002F\u002Fplg.uwaterloo.ca\u002F~gvcormac\u002Fcormacksigir09-rrf.pdf), agentic-search vs. RAG decomposition |\n| Progress Tracking | Claude Code `TodoWrite` (three fields), [DeepAgents `TodoListMiddleware`](https:\u002F\u002Fgithub.com\u002Flangchain-ai\u002Fdeepagents), DeerFlow context-loss detection, Anthropic effective-context-engineering (U-shaped attention) |\n| Failure Journals | [Hermes Agent error_classifier (13 FailoverReason)](https:\u002F\u002Fgithub.com\u002Fopenhermes\u002Fagent), [Aider self-heal loop](https:\u002F\u002Fgithub.com\u002FAider-AI\u002Faider\u002Fblob\u002Fmain\u002Faider\u002Fcoders\u002Fbase_coder.py), [Manus *Context Engineering*](https:\u002F\u002Fmanus.im\u002Fblog\u002FContext-Engineering-for-AI-Agents-Lessons-from-Building-Manus), [arxiv:2509.25370 *Where LLM Agents Fail*](https:\u002F\u002Farxiv.org\u002Fabs\u002F2509.25370) |\n| Chain of Thought | Claude Code thinking three iron rules (`query.ts:151-163`), Hermes `_strip_reasoning_tags`, Anthropic Think-as-Tool (Tau-bench +20pp), [OpenAI 2026 CoT controllability + monitorability](https:\u002F\u002Fopenai.com\u002Findex\u002Fevaluating-chain-of-thought-monitorability\u002F) |\n| Complexity Routing | Claude Code `FallbackTriggeredError`, [Hermes 6-tier `ReasoningEffort`](https:\u002F\u002Fgithub.com\u002Fopenhermes\u002Fagent), Aider `--model` + `--weak-model`, [Anthropic *Building Effective Agents*](https:\u002F\u002Fwww.anthropic.com\u002Fresearch\u002Fbuilding-effective-agents) |\n| Parallel Exploration | [Wang 2022 Self-Consistency](https:\u002F\u002Farxiv.org\u002Fabs\u002F2203.11171), [Yao 2023 Tree of Thoughts](https:\u002F\u002Farxiv.org\u002Fabs\u002F2305.10601), [CoT-PoT N=2 → 90% of N=10 lift](https:\u002F\u002Farxiv.org\u002Fabs\u002F2406.14833), DeerFlow isolated event-loop |\n| Iterative Hypothesis | [Anthropic 2026 three-agent harness (Planner\u002FGenerator\u002FEvaluator)](https:\u002F\u002Fwww.anthropic.com\u002Fresearch\u002Fmulti-agent-research), [ReAct (Yao 2022)](https:\u002F\u002Farxiv.org\u002Fabs\u002F2210.03629), [ReWOO (Xu 2023)](https:\u002F\u002Farxiv.org\u002Fabs\u002F2305.18323), [Self-Refine (Madaan 2023)](https:\u002F\u002Farxiv.org\u002Fabs\u002F2303.17651), Karl Popper falsificationism |\n| Tool Dispatch | Claude Code `Tool.ts` 14-field schema, [Anthropic Programmatic Tool Calling](https:\u002F\u002Fplatform.claude.com\u002Fdocs\u002Fen\u002Fagents-and-tools\u002Ftool-use\u002Fprogrammatic-tool-calling), Codex CLI `execpolicy` crate, [arxiv:2602.14878 *MCP Tool Descriptions Are Smelly*](https:\u002F\u002Farxiv.org\u002Fhtml\u002F2602.14878v1), [OWASP Top 10 for Agentic Apps 2026 A2](https:\u002F\u002Fgenai.owasp.org\u002F), Manus 32-tool ceiling |\n| Plan-and-Execute | [Aider `architect_coder.py` (9-line core)](https:\u002F\u002Fgithub.com\u002FAider-AI\u002Faider\u002Fblob\u002Fmain\u002Faider\u002Fcoders\u002Farchitect_coder.py), Claude Code ExitPlanMode (plan-as-file), [LangGraph 1.0 BSP\u002FPregel](https:\u002F\u002Fblog.langchain.com\u002Fbuilding-langgraph\u002F), Manus `todo.md`, [Anthropic Adaptive Replanning](https:\u002F\u002Fwww.anthropic.com\u002Fresearch\u002Fmulti-agent-research) |\n| Prompt Chaining | [Aider `history.py` 49-line recursive chain](https:\u002F\u002Fgithub.com\u002FAider-AI\u002Faider\u002Fblob\u002Fmain\u002Faider\u002Fhistory.py), Claude Code PRA loop + Skills + slash commands, [Anthropic *Building Effective Agents*](https:\u002F\u002Fwww.anthropic.com\u002Fresearch\u002Fbuilding-effective-agents), [Anthropic prompt best practices (XML structure)](https:\u002F\u002Fplatform.claude.com\u002Fdocs\u002Fen\u002Fbuild-with-claude\u002Fprompt-engineering\u002Fclaude-prompting-best-practices), Doug McIlroy Unix philosophy |\n| Guardrail Sandwich | Claude Code Hooks Pipeline (12 lifecycle events; PreToolUse blocks), [OWASP Top 10 for Agentic Apps 2026 A1\u002FA2\u002FA3](https:\u002F\u002Fgenai.owasp.org\u002F), NVIDIA NeMo Guardrails (Colang 4-rail), GuardrailsAI (RAIL spec), Microsoft Guidance (grammar-level), [arxiv:2509.23994 *Policy-as-Prompt Synthesis*](https:\u002F\u002Farxiv.org\u002Fabs\u002F2509.23994) |\n\nThe eight production harnesses the framework tracks: **Claude Code,\nCodex CLI, Aider, OpenCode, OpenClaw, Hermes Agent, DeepAgents, DeerFlow,\nOpenHands**. Each pattern's README pulls from at least one of these to\nshow the pattern in real production form, not toy form.\n\n---\n\n## What this repo is not\n\n* **Not a framework.** Use [LangGraph](https:\u002F\u002Fgithub.com\u002Flangchain-ai\u002Flanggraph),\n  [agno](https:\u002F\u002Fgithub.com\u002Fagno-agi\u002Fagno),\n  [DeerFlow](https:\u002F\u002Fgithub.com\u002Fbytedance\u002Fdeer-flow), or\n  [OpenHands](https:\u002F\u002Fgithub.com\u002FAll-Hands-AI\u002FOpenHands) for a production\n  runtime. This repo is the design vocabulary you apply on top of any of\n  them. Switching frameworks does not change the matrix.\n* **Not a flat catalog.** A list answers *what patterns exist*. The matrix\n  answers *where a problem sits* and *which patterns are wrong for that\n  position*.\n* **Not toy code.** Every `pattern.py` is small (50–250 lines) on\n  purpose, but it is honest code with real invariants and tests. Each\n  `example.py` runs on data shaped like production. Engineering slices\n  in the READMEs cite verified upstream files.\n\n---\n\n## Quickstart\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fhuangjia2019\u002Fagent-design-patterns.git\ncd agent-design-patterns\npython -m venv .venv && source .venv\u002Fbin\u002Factivate\npip install -e \".[dev]\"\n\n# Run a pattern's case\npython perception\u002Fa-context-triage\u002Fexample.py\npython perception\u002Fb-semantic-compaction\u002Fexample.py\n\n# Run all invariant tests\npytest\n```\n\nEach pattern folder is self-contained. No central framework, no plugin\nsystem to learn. Read the folder's README, look at `pattern.py`, run\n`example.py`, read the tests.\n\n---\n\n## How to read a pattern folder\n\n```\n\u003Cpattern-folder>\u002F\n  README.md                # The why — what failure mode this pattern catches\n  README.zh-CN.md          # 中文版\n  pattern.py               # The minimal honest implementation\n  example.py               # A runnable case on production-shaped data\n  test_pattern.py          # The invariants the pattern must hold\n```\n\nRead the README first — it's the *why* and the upstream slice. Then read\n`pattern.py` to see the smallest amount of code that solves it. Run\n`example.py` to see it work on data with shape. Tests pin the invariants\nyou must not break when adapting.\n\n---\n\n## The thesis behind the framework\n\nThree lines from the book:\n\n* *Designing an agent is solving a constrained allocation problem.*\n* *A fixed token budget must be distributed across competing cognitive\n  demands under non-deterministic execution paths.*\n* *The model is the spender. The harness is the budgeter. The patterns\n  are the strategies.*\n\nEvery pattern in the matrix is a strategy for one of those three roles —\nhow the harness budgets, how the patterns allocate, how the model is\npositioned to spend. The matrix is what makes the strategies discussable\nas a system rather than as a flat list.\n\n---\n\n## Book · Column · Newsletter\n\n| | |\n|---|---|\n| **Manning** · *[Designing AI Agents](https:\u002F\u002Fhubs.la\u002FQ04hCsH10)* | The design-pattern catalogue for production AI agents. 27 patterns across 7 cognitive functions and 6 topologies. |\n| **极客时间** · *[《Agent 设计模式之美》](https:\u002F\u002Ftime.geekbang.org\u002F)* | Chinese-language video column. Pattern-by-pattern walkthrough with engineering slices from real production harnesses. |\n| **Substack** · *[Agent Design Patterns](https:\u002F\u002Fagentpatterns.substack.com)* | Free English newsletter, one essay every 1–2 weeks. Structural observation, not hype. |\n| **极客时间** · *[Claude Code 工程化实战](https:\u002F\u002Ftime.geekbang.org\u002F)* | Published Chinese-language video column on the engineering practice of building agents on Claude Code. |\n\nThe book gives you the theory. The column gives you the lectures. This\nrepo gives you runnable code.\n\n---\n\n## Author\n\n[Jia Huang (黄佳)](https:\u002F\u002Fkage-ai.com) — Lead Research Engineer at A*STAR\nSingapore, formerly senior consultant at Accenture Singapore.\nTwenty years across NLP, LLMs, and AI applications in MedTech and\nFinTech. Author of two forthcoming English-language books (*Designing AI\nAgents* with Manning, *RAG from First Principles* with Packt) and six\nChinese-language books on machine learning, GPT, AI agents, RAG, and\ndata analysis with cumulative readers in the hundreds of thousands.\n\nThe two-axis framework is the author's original contribution; the\nconstituent elements (seven cognitive functions, six execution\ntopologies) are not new — the contribution is the orthogonal organization.\n\n[kage-ai.com](https:\u002F\u002Fkage-ai.com) · [LinkedIn](https:\u002F\u002Fwww.linkedin.com\u002Fin\u002Fhuangjia2019\u002F) · [Substack](https:\u002F\u002Fagentpatterns.substack.com) · [tohuangjia@gmail.com](mailto:tohuangjia@gmail.com)\n\n---\n\n## Contributing\n\nIssues welcome. Particularly useful:\n\n* **Citation drift** — a verified engineering slice in a README points at\n  a file or line that no longer matches upstream\n* **Invariant violations** — a test misses a case that you've seen the\n  pattern fail in production\n* **New language ports** — TypeScript \u002F Go ports of any pattern, opened\n  as a separate top-level folder\n* **New engineering slices** — a production harness you've worked with\n  shows the pattern in a form not yet documented in the README\n\nPull requests for new patterns: please open an issue first to discuss\nwhere the pattern sits in the matrix.\n\n---\n\n## Citation\n\nIf this framework is useful in your work, please cite the paper:\n\n```bibtex\n@misc{huang_zhou_2026_dual_axis,\n  author        = {Huang, Jia and Zhou, Joey Tianyi},\n  title         = {A Two-Dimensional Framework for AI Agent Design Patterns:\n                   Cognitive Function and Execution Topology},\n  year          = {2026},\n  eprint        = {2605.13850},\n  archivePrefix = {arXiv},\n  primaryClass  = {cs.AI},\n  doi           = {10.5281\u002Fzenodo.19036557},\n  url           = {https:\u002F\u002Farxiv.org\u002Fabs\u002F2605.13850}\n}\n```\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","2026-06-11 04:10:49","CREATED_QUERY"]