🤖 Agentic Design Patterns

中文版

Transform your AI applications from simple prompts to sophisticated intelligent systems.

🧭 Principles

This repo is built around four commitments. They explain what stays in and what gets cut.

1. Lean, not exhaustive. This is not a catalog of hundreds of patterns that no human will ever read, understand, or remember. It is a lean catalog meant to be understood and memorized. Long patterns lists are not features; they are noise.
2. Hard cap: at most 24 patterns. If a pattern is not necessary, we remove it. If something new is added, something else gets dropped. The ceiling is a forcing function, not an aspiration. Status (2026-05): 29 patterns today; pruning is actively in progress toward the 24-cap, with each cut justified in diff.md.
3. Demos must actually work. Every demo runs in an automated weekly smoke test, for both Python and TypeScript — and it must pass. (See .github/workflows/weekly-smoke.yml.) Educational code that doesn't run is educational code that lies.
4. Concrete relevance, not just papers. For each pattern we measure how it shows up in real coding agents — currently Pi — and write it down in a pi.md inside each pattern folder, plus a repo-wide roll-up with a coverage heat map. We also maintain diff.md to disambiguate commonly-confused pattern pairs: if two patterns can't be cleanly told apart, one of them probably doesn't belong here. A pattern that only exists in a paper somewhere is a signal it may not belong either.

---

AI evolves too quickly for traditional books to stay current, especially in fast-moving areas like agentic systems. That’s why this is one of the best “living books” on agentic AI: a comprehensive, hands-on collection of design patterns for building robust AI agents, continuously updated with real-world implementations, practical examples, and detailed architectural guidance for scalable, maintainable AI applications.

Table of Contents

• 📚 Academic Foundations
• 🏗️ Repository Structure
• 🗂️ Patterns at a Glance
• 📚 Foundational Patterns
• 🧠 Advanced Reasoning Patterns
• 🛡️ Reliability Patterns
• 🎯 Orchestration Patterns
• 📊 Observability Patterns
• 🧩 Memory Patterns
• 🎓 Learning Patterns
• 🚀 Quick Start
• 🗺️ Pattern Selection Guide
• 🎓 Learning Path
• 🛠️ Tech Stack
• 📖 Resources
• 🏛️ Standards & Compliance
• 📌 How to Cite
• 🙏 Acknowledgments

New: Pi implementation analyses

This repository now includes implementation-focused analyses of how they map to Pi, grounded in the actual Pi codebase with package/module references, line-numbered excerpts, and notes on architectural tradeoffs or limitations.

Look for pi.md inside pattern folders. These writeups stay conservative: if Pi does not meaningfully implement a pattern, the analysis says so explicitly rather than forcing a match.

See the Pi roll-up summary (pi.md) for a coverage heat map and one-line verdicts across all 28 patterns.

Currently available Pi analyses:

• Foundational: Prompt Chaining, Routing, Parallelization, Reflection, Tool Use, Planning, Multi-Agent Collaboration, ReAct, HITL, Structured Outputs, Computer Use
• Reasoning: Tree of Thoughts, Graph of Thoughts, Exploration & Discovery, Deep Research
• Reliability: Error Recovery, Guardrails
• Orchestration: Goal Management, Subagents, Skills, Agent Communication, MCP, Prioritization
• Observability: Evaluation & Monitoring, Resource Optimization
• Memory: Memory Management, Context Management
• Learning: Adaptive Learning

---

📚 Academic Foundations

This repository implements design patterns grounded in peer-reviewed research and industry best practices. Key academic contributions include:

Core Research Papers

Reasoning and Acting

• ReAct: Synergizing Reasoning and Acting in Language Models (Yao et al., 2022, ICLR 2023) Foundational paper demonstrating that interleaving reasoning traces with actions creates synergy superior to separate reasoning or acting approaches. Directly implemented in our ReAct pattern.

Advanced Reasoning Frameworks

• Tree of Thoughts: Deliberate Problem Solving with Large Language Models (Yao et al., 2023, NeurIPS 2023) Generalizes Chain-of-Thought by enabling exploration over coherent reasoning paths with self-evaluation and backtracking. Implemented in our Tree of Thoughts pattern.

• Graph of Thoughts: Solving Elaborate Problems with Large Language Models (Besta et al., 2023) Extends reasoning to arbitrary graph structures, enabling thought merging and non-hierarchical connections. Achieves 62% quality improvement with 31% cost reduction. Implemented in our Graph of Thoughts pattern.

Agentic RAG

• Agentic Retrieval-Augmented Generation: A Survey on Agentic RAG (Singh et al., 2025) Comprehensive survey of autonomous AI agents managing retrieval strategies through reflection, planning, tool use, and multi-agent collaboration—transcending static RAG limitations. Informs our RAG and Multi-Agent patterns.

Research Impact

These patterns represent the evolution from:

• Chain-of-Thought (linear reasoning) → Tree of Thoughts (branching exploration) → Graph of Thoughts (networked reasoning)
• Static RAG (fixed retrieval) → Agentic RAG (autonomous, adaptive retrieval)
• Single-agent systems → Multi-agent collaboration with specialized roles and communication protocols

---

🏗️ Repository Structure

agentic_design_patterns/
├── foundational_design_patterns/
│   ├── 1_prompt_chain/         # Sequential task decomposition
│   ├── 2_routing/              # Intelligent query routing
│   ├── 3_parallelization/      # Concurrent execution
│   ├── 4_reflection/           # Iterative refinement
│   ├── 5_tool_use/             # External system integration
│   ├── 6_planning/             # Strategic task planning
│   ├── 7_multi_agent_collaboration/  # Coordinated agents
│   ├── 8_react/                # Reasoning and acting
│   ├── 9_rag/                  # Retrieval-augmented generation
│   ├── 10_hitl/                # Human-in-the-loop
│   ├── 11_structured_outputs/  # Schema-constrained outputs
│   └── 12_computer_use/        # Browser/UI automation
│
├── reasoning/                  # Advanced reasoning patterns
│   ├── tree_of_thoughts/       # Systematic exploration
│   ├── graph_of_thoughts/      # Non-hierarchical reasoning
│   ├── exploration_discovery/  # Novel solution discovery
│   └── deep_research/          # Iterative research loops
│
├── reliability/                # Safety and resilience
│   ├── error_recovery/         # Failure handling
│   └── guardrails/             # Safety constraints
│
├── orchestration/              # Multi-agent coordination
│   ├── goal_management/        # Objective decomposition
│   ├── subagents/              # Orchestrator-worker topology
│   ├── skills/                 # Agent-loadable capability packages
│   ├── agent_communication/    # Inter-agent messaging
│   ├── mcp/                    # Model Context Protocol
│   └── prioritization/         # Task ranking
│
├── observability/              # Monitoring and optimization
│   ├── evaluation_monitoring/  # Metrics and quality
│   └── resource_optimization/  # Cost and performance
│
├── memory/                     # Context and history
│   ├── memory_management/      # Long-term memory
│   └── context_management/     # Context optimization
│
├── learning/                   # Continuous improvement
│   └── adaptive_learning/      # Learning from feedback
│
├── tests/                      # Repo-level reliability smoke tests
├── .github/workflows/          # CI workflows
├── repo_support.py             # Shared runtime/bootstrap helper
├── .env                        # Environment variables
├── LICENSE                     # MIT License
└── README.md                   # This file

---

🗂️ Patterns at a Glance

One-row-per-pattern index for fast navigation. Each row links to the pattern's deep-dive directory; the Pi column links to its pi.md implementation analysis where available; the TS column marks patterns with a Bun/TypeScript port under <pattern>/typescript/.

#	Pattern	Category	Pi Analysis	TypeScript
1	Prompt Chaining	Foundational	pi	✓
2	Routing	Foundational	pi	✓
3	Parallelization	Foundational	pi	✓
4	Reflection	Foundational	pi	✓
5	Tool Use	Foundational	pi	✓
6	Planning	Foundational	pi	✓
7	Multi-Agent Collaboration	Foundational	pi	✓
8	ReAct	Foundational	pi	✓
9	RAG	Foundational	—	✓
10	Human-in-the-Loop (HITL)	Foundational	pi	✓
11	Structured Outputs	Foundational	pi	✓
12	Computer Use	Foundational	pi	✓
13	Tree of Thoughts	Reasoning	pi	—
14	Graph of Thoughts	Reasoning	pi	—
15	Exploration & Discovery	Reasoning	pi	—
16	Deep Research	Reasoning	pi	—
17	Error Recovery	Reliability	pi	—
18	Guardrails	Reliability	pi	—
19	Goal Management	Orchestration	pi	—
20	Subagents	Orchestration	pi	—
21	Skills	Orchestration	pi	—
22	Agent Communication	Orchestration	pi	—
23	MCP	Orchestration	pi	—
24	Prioritization	Orchestration	pi	—
25	Evaluation & Monitoring	Observability	pi	—
26	Resource Optimization	Observability	pi	—
27	Memory Management	Memory	pi	—
28	Context Management	Memory	pi	—
29	Adaptive Learning	Learning	pi	—

---

📚 Foundational Patterns

1️⃣ Prompt Chaining

Break complex tasks into sequential, manageable steps

# Transform a monolithic prompt into a chain of specialized prompts
input → extract_data → transform → validate → final_output

When to use:

• Multi-step transformations (data extraction → analysis → formatting)
• Tasks requiring intermediate validation
• Complex workflows that benefit from decomposition

Key benefits:

• 🎯 Better accuracy through focused prompts
• 🔍 Easier debugging with visible intermediate steps
• 🔄 Reusable components across workflows

📖 Learn More → · 🔎 Pi Analysis →

---

2️⃣ Routing

Intelligently direct queries to specialized handlers

# Dynamic routing based on query classification
user_query → classifier → [technical_expert | sales_agent | support_bot]

When to use:

• Multi-domain applications (support, sales, technical)
• Specialized model selection (fast/cheap vs. slow/accurate)
• Intent-based workflows requiring different processing paths

Key benefits:

• 💰 Cost optimization (use expensive models only when needed)
• ⚡ Performance gains (route simple queries to fast handlers)
• 🎨 Specialized handling (domain experts for domain queries)

📖 Learn More → · 🔎 Pi Analysis →

---

3️⃣ Parallelization

Execute independent operations simultaneously for dramatic speedups

# Sequential: 15 seconds          # Parallel: 5 seconds
task_a(5s) →                      task_a(5s) ↘
task_b(5s) →          vs.         task_b(5s) → combine → output
task_c(5s) → output               task_c(5s) ↗

When to use:

• Multiple API calls (search engines, databases, external services)
• Parallel data processing (analyze multiple documents)
• Multi-source research or content generation

Key benefits:

• ⚡ 2-10x faster execution for I/O-bound tasks
• 📈 Better resource utilization
• 🚀 Improved user experience through reduced latency

📖 Learn More → · 🔎 Pi Analysis →

---

4️⃣ Reflection

Iteratively improve outputs through systematic critique and refinement

One of the four core agentic design patterns (Ng, 2024), reflection enables AI to systematically critique and improve its own outputs.

# Single-shot: 5/10 quality        # With reflection: 8.5/10 quality
input → generate → done            input → generate → critique → 
                                          refine → critique → final

When to use:

• High-stakes content (code, legal docs, published articles)
• Complex reasoning tasks (logic puzzles, strategic planning)
• Quality-critical applications where "good enough" isn't enough

Key benefits:

• 🎯 50-70% higher quality scores
• 🔍 Systematic error detection and correction
• 🧠 Self-improving outputs without human intervention

Trade-offs:

• ⚠️ 3-5x higher token costs
• ⏱️ 4-8x longer execution time

📖 Learn More → · 🔎 Pi Analysis →

---

5️⃣ Tool Use

Enable LLMs to interact with external systems and APIs

Essential for grounding LLM outputs in real-world data and actions, tool use is a foundational capability of modern agentic systems (Ng, 2024; Yao et al., 2022).

# Without tools: Limited to training data
# With tools: Access real-time data and take actions
user_query → LLM decides → call_weather_api(location) → integrate_result → response

When to use:

• Real-time data retrieval (weather, stock prices, news)
• Private/proprietary data access (databases, CRM systems)
• Precise calculations or code execution
• External actions (send emails, update records, control devices)

Key benefits:

• 🌐 Access to live, dynamic information
• 🎯 Precise calculations and data validation
• 🔧 Integration with existing enterprise systems
• 💰 Reduced token costs (fetch vs. embed in prompts)

Trade-offs:

• ⚠️ Added latency per tool call
• 🔒 Security considerations (authentication, validation)

📖 Learn More → · 🔎 Pi Analysis →

---

6️⃣ Planning

Decompose complex goals into structured, executable action plans

A fundamental capability for agentic systems (Ng, 2024), enabling AI to decompose complex objectives strategically rather than responding reactively.

# Without planning: Reactive, incomplete execution
# With planning: Strategic breakdown and systematic execution
complex_goal → analyze → decompose → plan_steps → execute_sequentially → final_result

When to use:

• Multi-step workflows requiring orchestration (research reports, data pipelines)
• Tasks with interdependent operations
• Complex problem-solving requiring strategic thinking
• Workflow automation (onboarding, procurement, project setup)

Key benefits:

• 🎯 Structured approach to complex objectives
• 🧠 Strategic thinking vs. reactive responses
• 🔄 Adaptability through dynamic replanning
• 📊 Transparency into execution strategy

Trade-offs:

• ⚠️ Planning overhead (+20-40% tokens, 5-15s latency)
• 🛠️ Requires sophisticated state management

📖 Learn More → · 🔎 Pi Analysis →

---

7️⃣ Multi-Agent Collaboration

Coordinate multiple specialized agents to solve complex tasks

Multi-agent systems, highlighted in both the Agentic RAG survey (Singh et al., 2025) and production deployments (LangChain, 2024), enable sophisticated task distribution and specialized expertise.

# Agents as a team: specialize roles + coordinate communication
user_goal → manager/planner → [researcher | coder | designer | writer | reviewer] → synthesize → final_output

When to use:

• Complex tasks requiring diverse expertise (research + writing + QA)
• Workflows with distinct stages (research → draft → edit → package)
• Tool-specialized roles (web search, code execution, image generation)
• Quality-critical pipelines (critic/reviewer loops)

Key benefits:

• 🧩 Modularity: build and improve one role at a time
• 🛡️ Robustness: reviewers catch errors / reduce hallucinations
• ⚡ Parallelism: split independent workstreams for speed
• ♻️ Reuse: agents can be reused across multiple products

Common collaboration models:

• Sequential handoffs (linear pipeline)
• Supervisor/manager orchestration (hierarchical)
• Parallel workstreams (merge results)
• Debate/consensus (evaluate options)
• Critic–reviewer (quality enforcement)
• Network/all-to-all (exploratory, less predictable)
• Custom hybrids (fit domain constraints)

📖 Learn More → · 🔎 Pi Analysis →

---

8️⃣ ReAct (Reasoning and Acting) (Yao et al., 2022)

Interleave reasoning traces with tool execution for adaptive problem-solving

Originally introduced by Yao et al. (2022) in the paper "ReAct: Synergizing Reasoning and Acting in Language Models," this pattern demonstrates that interleaving reasoning traces with task-specific actions creates superior synergy compared to treating reasoning and acting as separate capabilities.

# Traditional: Direct action without explicit reasoning
user_query → tool_call → response

# ReAct: Explicit reasoning + grounded actions
user_query → Thought (reason) → Action (tool) → Observation (result) →
             Thought (adapt) → Action → Observation → Final Answer

When to use:

• Multi-step research requiring information lookup and verification
• Complex problem-solving where the solution path isn't predetermined
• Tasks requiring adaptation based on intermediate results
• Debugging and exploratory analysis
• Need transparent reasoning for interpretability

Key benefits:

• 🧠 Explicit reasoning traces improve decision quality
• 🎯 Grounded actions reduce hallucinations
• 🔄 Dynamic adaptation based on observations
• 🔍 Transparent and debuggable decision-making
• ✓ Self-correction and error recovery

Trade-offs:

• ⚠️ Higher latency (multiple reasoning + action cycles)
• 💰 Increased token costs (reasoning traces + tool calls)
• 🔁 Risk of unproductive loops without iteration limits

📖 Learn More → · 🔎 Pi Analysis →

---

9️⃣ RAG (Retrieval-Augmented Generation)

Ground LLM responses with relevant external knowledge

This approach, enhanced by agentic capabilities as described in the recent survey by Singh et al. (2025), enables autonomous AI agents to dynamically manage retrieval strategies through reflection, planning, and tool use—transcending the limitations of static RAG workflows.

# Without RAG: Limited to training data
user_query → LLM → response (may hallucinate)

# With RAG: Knowledge-grounded responses
user_query → retrieve_relevant_docs → augment_context → LLM → grounded_response

When to use:

• Dynamic or frequently updated information (documentation, product catalogs)
• Private/proprietary knowledge bases
• Domain-specific expertise beyond LLM training
• Reducing hallucinations with factual grounding

Key benefits:

• 📚 Access to current and proprietary information
• 🎯 Reduced hallucinations through grounding
• 💰 No retraining needed for knowledge updates
• 🔍 Source attribution and transparency

📖 Learn More →

---

🔟 Human-in-the-Loop (HITL)

Integrate human oversight and approval into AI workflows

The Human-in-the-Loop (HITL) pattern represents a pivotal strategy in agentic AI systems, deliberately interweaving the unique strengths of human cognition—such as judgment, creativity, and nuanced understanding—with the computational power and efficiency of AI. This strategic integration ensures that AI operates within ethical boundaries, adheres to safety protocols, and achieves its objectives with optimal effectiveness.

# Without HITL: Fully automated
agent_action → execute → result

# With HITL: Human checkpoint
agent_proposal → human_review → [approve|reject|modify] → execute → result

When to use:

• High-stakes decisions (financial transactions, legal actions, sentencing)
• Quality-critical content (publications, customer communications)
• Compliance and regulatory requirements
• Complex scenarios requiring nuanced judgment
• Learning from human expertise for continuous improvement
• Tasks involving ambiguity beyond reliable LLM capabilities

Key aspects:

• Human Oversight: Monitoring AI performance via dashboards/logs to ensure guideline adherence
• Intervention & Correction: Human operators rectify errors or guide agents in ambiguous scenarios
• Feedback for Learning: Human preferences inform agent learning (e.g., RLHF)
• Decision Augmentation: AI provides analysis/recommendations; humans make final decisions
• Human-Agent Collaboration: Cooperative interaction leveraging respective strengths
• Escalation Policies: Protocols dictating when agents escalate tasks to humans

Key benefits:

• 🛡️ Safety and risk mitigation in critical domains
• ✅ Quality assurance and compliance
• 🎓 Continuous learning from human feedback
• 🤝 Building user trust through transparency
• 🎯 Nuanced judgment in complex scenarios
• 🔄 Feedback loops for ongoing improvement

Practical applications:

• Content Moderation: AI filters at scale; humans review ambiguous cases
• Autonomous Driving: AI handles most tasks; humans take control in complex situations
• Financial Fraud Detection: AI flags patterns; human analysts investigate high-risk alerts
• Legal Document Review: AI scans/categorizes; lawyers review for accuracy and implications
• Customer Support: Chatbots handle routine queries; complex/emotional cases escalate to humans
• Data Labeling: Humans provide ground truth labels for training datasets
• Generative AI Refinement: Human editors review/refine LLM outputs for quality and brand alignment
• Autonomous Networks: AI analyzes KPIs; humans approve critical network changes

Trade-offs & caveats:

• ⚠️ Scalability limitations: Human oversight cannot handle millions of tasks
• 👥 Expertise dependency: Effectiveness relies on skilled domain experts
• 🔒 Privacy concerns: Sensitive information requires anonymization
• 💰 Cost considerations: Human review adds operational overhead

"Human-on-the-loop" variation: In this approach, human experts define overarching policies, while AI handles immediate actions to ensure compliance (e.g., automated trading within human-defined rules, call center routing based on manager-set policies).

📖 Learn More → · 🔎 Pi Analysis →

---

1️⃣1️⃣ Structured Outputs

Enforce schema-valid LLM outputs for reliable downstream automation

# Naive parsing (brittle)
text → prompt_json_request → parse_string_json → runtime_fail

# Structured outputs (reliable)
text → response_schema(Pydantic/JSON Schema) → validated_object → safe_automation

Key benefits: Schema guarantees, lower parsing failures, safer agent loops

📖 Learn More → · 🔎 Pi Analysis →

---

1️⃣2️⃣ Computer Use

Automate browser/UI workflows with explicit safety controls

# Observe → Think → Act loop for UI tasks
screenshot/state → reasoning → ui_action(click/type/navigate) → observation → iterate

Key benefits: Legacy-system automation, UI QA workflows, non-API task coverage

📖 Learn More → · 🔎 Pi Analysis →

---

🧠 Advanced Reasoning Patterns

Tree of Thoughts (Yao et al., 2023)

Explore multiple reasoning paths systematically

Introduced at NeurIPS 2023, Tree of Thoughts (ToT) generalizes Chain-of-Thought prompting by enabling LLMs to explore multiple reasoning paths, self-evaluate choices, and backtrack when necessary—enabling deliberate problem solving for complex tasks.

# Chain of Thought: Linear reasoning
input → step1 → step2 → step3 → answer

# Tree of Thoughts: Branching exploration
input → [thought1, thought2, thought3] → evaluate → expand_best →
        [refined_thoughts] → evaluate → solution

Key benefits: Better solutions through systematic exploration, backtracking capability, transparent decision trees

📖 Learn More → · 🔎 Pi Analysis →

---

Graph of Thoughts (Besta et al., 2023)

Enable non-hierarchical thought connections and merging

Building on ToT, Graph of Thoughts extends the reasoning paradigm from hierarchical trees to arbitrary graphs, enabling non-linear thought connections and aggregation—achieving 62% better quality on sorting tasks while reducing costs by 31% (Besta et al., 2023).

# Thoughts can reference and build on ANY other thought (not just parent-child)
input → generate_perspectives → connect_thoughts → aggregate → synthesis

Key benefits: Multi-perspective analysis, thought merging, flexible reasoning paths

📖 Learn More → · 🔎 Pi Analysis →

---

Exploration & Discovery

Discover novel solutions through guided exploration

# Epsilon-greedy: Balance exploration vs. exploitation
query → [explore_new | exploit_best] → evaluate → update_strategy → iterate

Key benefits: Novel solution discovery, avoiding premature convergence, adaptive exploration

📖 Learn More → · 🔎 Pi Analysis →

---

Deep Research

Run iterative research loops with gap-driven follow-up queries

# Plan → Search → Read → Reflect → Follow-up → Synthesize
question → sub_queries → retrieve_sources → identify_gaps → refine_queries → cited_output

Key benefits: Better coverage, fewer blind spots, stronger citation quality

📖 Learn More → · 🔎 Pi Analysis →

---

🛡️ Reliability Patterns

Error Recovery

Gracefully handle failures and self-correct

# Detect → Diagnose → Recover → Verify
operation → [success | failure] → classify_error → [retry | fallback | self_correct] → verify

Key benefits: Resilience, graceful degradation, automatic self-healing, reduced downtime

📖 Learn More → · 🔎 Pi Analysis →

---

Guardrails

Enforce safety constraints and compliance

# Multi-layer validation
input → validate → process → validate_output → [pass | block] → log

Key benefits: Safety assurance, compliance, brand protection, risk reduction

📖 Learn More → · 🔎 Pi Analysis →

---

🎯 Orchestration Patterns

Goal Management

Decompose and track complex objectives

# Hierarchical decomposition with progress tracking
complex_goal → decompose → [subgoal1, subgoal2, subgoal3] →
              track_dependencies → execute → monitor → replan

Key benefits: Structured execution, progress visibility, adaptive planning, resource optimization

📖 Learn More → · 🔎 Pi Analysis →

---

Subagents (Orchestrator-Worker)

Spawn focused subagents with isolated context and structured summaries

lead_agent → decompose_task → spawn_workers_parallel → structured_summaries → synthesize

Key benefits: Context isolation, parallel throughput, cleaner synthesis

📖 Learn More → · 🔎 Pi Analysis →

---

Skills

Load capability packages on demand via metadata-first discovery

skill_catalog(metadata) → select_relevant_skill → load_SKILL_body → execute

Key benefits: Tool-scaling beyond flat lists, lower prompt load, modular capabilities

📖 Learn More → · 🔎 Pi Analysis →

---

Agent Communication (A2A)

Enable agents to coordinate through message passing

# Direct messaging, pub-sub, negotiation protocols
agent1 → message → agent2 → response → agent1

Key benefits: Loose coupling, dynamic discovery, scalability, fault tolerance

📖 Learn More → · 🔎 Pi Analysis →

---

Model Context Protocol (MCP)

Standardized tool and resource integration

# USB for AI: Standard interface for tools/data
LLM → discover_tools → invoke_tool(params) → receive_result → integrate

Key benefits: Standardization, reusability, interoperability, composability

📖 Learn More → · 🔎 Pi Analysis →

---

Prioritization

Optimize task ordering and resource allocation

# Multi-criteria scoring with dynamic rebalancing
tasks → score(urgency, impact, effort) → rank → schedule → execute

Key benefits: Resource optimization, deadline adherence, fairness, efficiency

📖 Learn More → · 🔎 Pi Analysis →

---

📊 Observability Patterns

Evaluation & Monitoring

Track performance and quality metrics

# Quantitative + qualitative metrics
operation → collect_metrics → evaluate_quality → aggregate → alert → visualize

Key benefits: Visibility, early detection, data-driven decisions, continuous improvement

📖 Learn More → · 🔎 Pi Analysis →

---

Resource Optimization

Reduce costs and improve performance

# Caching, batching, model routing
request → [cache_hit | cache_miss] → [cheap_model | expensive_model] → optimize

Key benefits: 65-80% cost reduction, faster responses, better UX

📖 Learn More → · 🔎 Pi Analysis →

---

🧩 Memory Patterns

Memory Management

Maintain conversation history and long-term memory

# Buffer + semantic memory
interaction → store → [buffer_memory | vector_memory] → retrieve_relevant → use

Key benefits: Context retention, personalization, learning from history

📖 Learn More → · 🔎 Pi Analysis →

---

Context Management

Optimize context window usage

# Dynamic selection and compression
content → score_relevance → compress → fit_window → optimize

Key benefits: 70-90% cost reduction, focused responses, better performance

📖 Learn More → · 🔎 Pi Analysis →

---

🎓 Learning Patterns

Adaptive Learning

Improve through feedback and continuous learning

# Learn from outcomes
action → feedback → analyze_patterns → adapt_strategy → improve

Key benefits: Continuous improvement, personalization, domain adaptation

📖 Learn More → · 🔎 Pi Analysis →

---

🚀 Quick Start

Prerequisites

# Python 3.11 or higher
python --version

# Install uv 
curl -LsSf https://astral.sh/uv/install.sh | sh

Installation

# Clone the repository
git clone https://github.com/gtesei/agentic_design_patterns.git
cd agentic_design_patterns

# Set up shared environment
echo "OPENAI_API_KEY=your_api_key_here" > .env

Repository Runtime Notes

• The repository requires Python 3.11+.
• Each pattern folder has its own pyproject.toml, so run uv sync inside the pattern you want to execute.
• Example scripts now use a shared bootstrap helper in repo_support.py to:
  • locate the repo root
  • load the root .env
  • make the repo importable from any pattern folder
• Set OPENAI_MODEL in your environment if you want to override the default example model:

export OPENAI_MODEL=gpt-4o-mini

• If you are behind a corporate SSL interception proxy, SSL bypass is now opt-in:

export AGENTIC_DISABLE_SSL=1

Run Your First Pattern

Python remains the canonical track. All current foundational patterns also include a Bun/TypeScript port under <pattern>/typescript/.

# Python
cd foundational_design_patterns/3_parallelization
[uv sync]
uv run python src/parallelization.py

# TypeScript
cd foundational_design_patterns/3_parallelization/typescript
[bun install]
bash run.sh

Foundational patterns with both Python and TypeScript implementations currently live under:

• foundational_design_patterns/1_prompt_chain
• foundational_design_patterns/2_routing
• foundational_design_patterns/3_parallelization
• foundational_design_patterns/4_reflection
• foundational_design_patterns/5_tool_use
• foundational_design_patterns/6_planning
• foundational_design_patterns/7_multi_agent_collaboration
• foundational_design_patterns/8_react
• foundational_design_patterns/9_rag
• foundational_design_patterns/10_hitl
• foundational_design_patterns/11_structured_outputs
• foundational_design_patterns/12_computer_use

For TypeScript workspace conventions, coverage, and runtime details, see typescript_base/TYPESCRIPT.md.

Reliability And Smoke Tests

Use these from the repo root:

# Python foundational offline smoke
bash scripts/run_demos_smoke.sh --mode basic

# TypeScript foundational offline smoke
bash scripts/run_demos_smoke_typescript.sh --mode basic

CI

GitHub Actions runs the reliability gate on pushes and pull requests:

• .github/workflows/reliability-gate.yml
• Python shared-runtime smoke via unittest
• foundational TypeScript type-checks via bun --bun tsc --noEmit
• foundational TypeScript offline smoke via scripts/run_demos_smoke_typescript.sh --mode basic

---

🗺️ Pattern Selection Guide

Choose Your Pattern Based on Your Needs:

Need speed? → Routing + Parallelization + Resource Optimization (caching, batching)

Need quality? → Reflection + RAG (grounded knowledge) + Evaluation & Monitoring

Need cost optimization? → Routing + Resource Optimization (65-80% savings) + Context Management

Need both speed AND quality? → Parallelization + Prompt Chaining + RAG

Complex multi-step workflow? → Prompt Chaining + Planning + Goal Management

Independent concurrent tasks? → Parallelization will give you massive speedups

High-stakes output? → Reflection + HITL (human approval) + Guardrails (safety)

External system integration? → Tool Use + MCP (standardized protocols)

Multi-step automation? → Planning + Goal Management + Agent Communication

Multiple roles working together? → Multi-Agent Collaboration + Agent Communication (A2A)

Exploratory multi-step tasks? → ReAct (reasoning + actions) or Tree of Thoughts (exploration)

Need transparent decision-making? → ReAct (explicit reasoning) + Evaluation & Monitoring

Need strict machine-readable outputs? → Structured Outputs + Guardrails

Need UI/browser automation? → Computer Use + HITL

Need iterative cited synthesis? → Deep Research + RAG

Need scalable multi-capability agents? → Subagents + Skills

Knowledge-grounded responses? → RAG retrieves relevant documents before generation

Complex reasoning tasks? → Tree of Thoughts (systematic) or Graph of Thoughts (multi-perspective)

Production reliability? → Error Recovery + Guardrails + Evaluation & Monitoring

Long conversations? → Memory Management + Context Management (optimize windows)

Continuous improvement? → Adaptive Learning + Evaluation & Monitoring (feedback loops)

Resource constraints? → Prioritization + Resource Optimization + Context Management

---

🎓 Learning Path

Beginner → Intermediate → Advanced → Expert

Phase 1: Foundations (Start Here)

1. Prompt Chaining - Foundation for everything
2. Routing - Learn to optimize model selection
3. Parallelization - Scale your applications
4. Reflection - Master quality optimization
5. Tool Use - Connect to external systems

Phase 2: Core Patterns 6. RAG - Knowledge-grounded responses 7. ReAct - Reasoning + acting 8. Planning - Strategic decomposition 9. HITL - Human oversight 10. Multi-Agent - Agent coordination

Phase 3: Advanced Reasoning 11. Tree of Thoughts - Systematic exploration 12. Graph of Thoughts - Multi-perspective reasoning 13. Exploration & Discovery - Novel solutions

Phase 4: Production Patterns 14. Error Recovery - Resilience 15. Guardrails - Safety 16. Evaluation & Monitoring - Metrics 17. Resource Optimization - Cost/performance

Phase 5: Orchestration & Memory 18. Goal Management - Objective tracking 19. Agent Communication - Messaging 20. MCP - Standardized integration 21. Prioritization - Task ranking 22. Memory Management - Context retention 23. Context Management - Optimization

Phase 6: Continuous Improvement 24. Adaptive Learning - Learning from feedback 25. Structured Outputs - Schema reliability 26. Computer Use - Browser/UI automation 27. Subagents - Orchestrator-worker topology 28. Skills - Capability packages 29. Deep Research - Iterative research loops

Each pattern builds on concepts from previous ones. Start with Phase 1, then explore other phases based on your needs.

---

🛠️ Tech Stack

Core Frameworks

• LangChain - Comprehensive framework for LLM applications
• LangGraph - Stateful workflows and multi-agent orchestration
• LangSmith - LLM application monitoring and evaluation

Models & APIs

• OpenAI Models - Primary provider used throughout the examples, configured via environment variables
• Anthropic Claude - Alternative frontier-model family with strong long-context support
• Other LLM Providers - Fully compatible through LangChain abstractions

Development Tools

• Pydantic - Data validation and structured outputs
• Python 3.11+ - Modern Python features (match/case, typing)
• uv - Fast Python package manager

Observability & Evaluation

• W&B Weave - Agent evaluation and monitoring
• LangSmith - Tracing and debugging

---

📖 Resources

🎓 Academic Papers & Surveys

Reasoning & Planning:

• ReAct: Synergizing Reasoning and Acting in Language Models (Yao et al., 2022) - ICLR 2023
• Tree of Thoughts: Deliberate Problem Solving with Large Language Models (Yao et al., 2023) - NeurIPS 2023
• Graph of Thoughts: Solving Elaborate Problems with Large Language Models (Besta et al., 2023)

Retrieval-Augmented Generation:

• Agentic Retrieval-Augmented Generation: A Survey on Agentic RAG (Singh et al., 2025)
• Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks (Lewis et al., 2020)

📚 Books

• Agentic Design Patterns: A Hands-On Guide to Building Intelligent Systems - Antonio Gullí (Springer Nature, 2024) - Primary inspiration for this repository
• Building LLM Powered Applications - Valentina Alto (Packt/O'Reilly, 2024)
• Hands-On Large Language Models - Jay Alammar & Maarten Grootendorst (O'Reilly, 2024)

🎓 Courses & Educational Content

Foundational Courses:

• Agentic AI with Andrew Ng (DeepLearning.AI, 2024) - Covers reflection, tool use, planning, and multi-agent collaboration

Framework-Specific:

• LangChain Academy - Official LangChain courses
• LangGraph Tutorials - Stateful agent workflows
• OpenAI Cookbook - Function calling and agent patterns
• Anthropic Prompt Engineering Interactive Tutorial

🏭 Industry Documentation & Guides

Official Framework Documentation:

• LangChain Documentation
• LangGraph Documentation
• Microsoft AutoGen
• OpenAI Function Calling Guide
• OpenAI Agents Platform
• Anthropic Prompt Engineering Guide

Production Best Practices:

• LangChain: Top 5 LangGraph Agents in Production 2024 - Real-world deployments
• Weights & Biases: Agentic RAG Guide

🌐 Community Resources

Curated Collections:

• Awesome-LangGraph - Comprehensive LangGraph ecosystem index
• Prompt Engineering Guide - Comprehensive guide covering latest papers and techniques
• Learn Prompting - Free generative AI guide

Related Projects:

• LangChain Templates
• Microsoft AutoGen
• CrewAI
• AG2 (formerly AutoGen)

🔬 Research Collections

• Papers with Code: Agents - Latest research with implementations
• arXiv: Artificial Intelligence - Recent AI papers
• Hugging Face Papers - Trending ML research

---

🏛️ Standards & Compliance

NIST AI Risk Management Framework

Organizations deploying agentic AI systems should consider the NIST AI Risk Management Framework and associated guidance:

Core Framework

• NIST AI Risk Management Framework (AI RMF 1.0) (January 2023) Voluntary framework to manage AI risks based on four core functions: Govern, Map, Measure, and Manage.

Generative AI Profile

• NIST AI RMF: Generative AI Profile (NIST.AI.600-1) (July 2024) Addresses risks unique to Generative AI, including governance, content provenance, pre-deployment testing, and incident disclosure. Includes catalog of 400+ mitigation actions.

Compliance Mapping

NIST AI RMF Function	Relevant Patterns
Govern	Human-in-the-Loop, Guardrails
Map	Planning, Goal Management
Measure	Evaluation & Monitoring, Adaptive Learning
Manage	Error Recovery, Guardrails

Key Focus Areas for Agentic Systems

• Transparency: ReAct pattern provides explicit reasoning traces for auditability
• Human Oversight: HITL pattern enables approval workflows
• Safety Constraints: Guardrails pattern enforces compliance boundaries
• Evaluation: Monitoring pattern tracks quality and bias metrics
• Error Recovery: Graceful degradation and incident response

Additional Resources

• AI Executive Order 14110
• EU AI Act
• ISO/IEC 42001:2023 - AI Management System standard

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

📌 How to Cite

If you reference this catalog in academic or professional work, please cite:

@misc{tesei_agentic_design_patterns,
  author       = {Tesei, Gino},
  title        = {Agentic Design Patterns: A Hands-On Catalog for Building Intelligent Systems},
  year         = {2024},
  publisher    = {GitHub},
  howpublished = {\url{https://github.com/gtesei/agentic_design_patterns}},
  note         = {MIT License}
}

---

🙏 Acknowledgments

This repository's structure and approach were inspired by:

Primary References

Gullí, Antonio, Agentic Design Patterns: A Hands-On Guide to Building Intelligent Systems, Springer Nature Switzerland, 2024.

Ng, Andrew, Agentic AI, DeepLearning.AI, 2024.

Academic Foundations

We gratefully acknowledge the research contributions that ground these patterns:

• Yao, Shunyu et al. - ReAct and Tree of Thoughts frameworks
• Singh, Aditi et al. - Agentic RAG survey and taxonomy
• Besta, Maciej et al. - Graph of Thoughts methodology
• Lewis, Patrick et al. - Foundational RAG research

Community & Tools

Special thanks to:

• The LangChain and LangGraph teams for building production-grade agentic frameworks
• The open-source AI community for advancing the state of the art
• NIST for providing guidance on trustworthy AI development
• Claude Code for assistance in developing and refining the implementations in this repository
• All contributors who help improve these patterns

---

⭐ Star History

If you find this repository helpful, please consider giving it a star! It helps others discover these patterns.

Built with ❤️ for the AI developer community

⬆ Back to Top