huangjia2019/agent-design-patterns

What it solves

This project provides a structured design vocabulary for building production-grade AI agents. Instead of a flat list of techniques, it organizes agent architectures into a two-dimensional matrix to help developers identify exactly which pattern is appropriate for a specific cognitive function and execution topology, preventing common failure modes like budget allocation errors or conflicting critics.

How it works

The framework organizes 27 core patterns across two orthogonal axes:

• Cognitive Function (What the agent is doing): perceive, remember, reason, act, reflect, collaborate, and govern.
• Execution Topology (How work is laid out): chain, route, parallel, loop, hierarchy, and orchestrate.

Each pattern is implemented as a self-contained folder containing a minimal reference implementation (pattern.py), a real-scenario example (example.py), and tests to ensure the pattern's invariants are maintained.

Who it’s for

AI engineers and architects who are building agents for production environments and need a systematic way to choose and compose architectural patterns beyond simple tutorials.

Highlights

• Two-Axis Matrix: Moves beyond flat lists to provide coordinates for agent design decisions.
• Production-Grounded: Every pattern cites verified "engineering slices" from real-world production harnesses like Claude Code, Aider, and OpenHands.
• Runnable Reference Code: Provides honest, small-scale implementations (50-250 lines) rather than toy examples.
• Comprehensive Catalog: Covers 27 core patterns including RAG, Chain of Thought, Guardrail Sandwich, and Hierarchical Delegation.