🤖 AI Agent Mastery

Master AI Agent Development from Zero to Production

A structured, hands-on curriculum for building real-world AI agents

Get Started • Curriculum • Status Board • Resources

---

🎯 Why This Repository?

The Problem: AI agent tutorials are scattered, outdated, or too theoretical. Most developers struggle to go from "hello world" to production-ready agents.

The Solution: A complete, structured learning path that takes you from basic chatbots to sophisticated multi-agent systems — with real-world projects, not toy examples.

What Makes This Different

Traditional Tutorials	This Curriculum
❌ Copy-paste code without understanding	✅ Build intuition through progression
❌ Outdated API patterns	✅ Latest LangChain/LangGraph (2024+)
❌ Toy examples ("count to 10")	✅ Real problems (support bots, research assistants)
❌ Skip error handling	✅ Production-ready patterns
❌ No clear path	✅ 33 structured tasks, 6 levels

---

🏗️ What You'll Build

Level 1: Foundation Agents
├── CLI Chatbot
├── Unit Converter with Tools
├── Task Manager (stateful)
├── Persistent Notes (SQLite memory)
├── Code Reviewer (structured output)
└── Standup Bot (multi-turn)

Level 2: Reasoning Patterns  
├── Math Solver (Chain-of-Thought)
├── Essay Improver (Self-Reflection)
├── Trip Planner (Plan-and-Execute)
├── Debate Simulator (Self-Consistency)
├── Bug Hunter (ReAct)
└── Recipe Adapter (Few-Shot)

Level 3: RAG & Knowledge
├── Docs Q&A Bot (Basic RAG)
├── Research Assistant (Agentic RAG)
├── Multi-Source Analyst
├── Self-Correcting Q&A (Self-RAG)
└── Fallback Search (Corrective RAG)

Level 4: Multi-Agent Systems
├── Blog Pipeline (Sequential)
├── Support Router (Conditional)
├── Fact Checker (Parallel)
├── Project Manager (Supervisor)
├── Devil's Advocate (Adversarial)
└── Startup Team (Role-based)

Level 5: Production Ready
├── Approval Workflow (HITL)
├── Resilient Agent (Error Handling)
├── Streaming Chat
├── Budget-Aware Agent
├── Persistent Workflows
└── Observable Agent (Monitoring)

Level 6: Mastery Capstones
├── Full-Stack Agent System
├── Pattern Decision Guide
├── Teach It Back
└── Novel Pattern Innovation

---

🚀 Quick Start

Prerequisites

• Python 3.12+
• OpenAI API key (or compatible LLM)
• Basic Python knowledge

Setup

# Clone the repository
git clone https://github.com/yourusername/ai-agent-mastery.git
cd ai-agent-mastery

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY

Track Your Progress

Option 1: CLI Tracker (Recommended)

python tracker.py              # Show dashboard
python tracker.py complete 1   # Mark issue #001 as done
python tracker.py next         # Show next task details
python tracker.py reset        # Reset all progress

Option 2: Web Dashboard (Gradio)

python dashboard.py            # Opens http://localhost:7860

Your First Agent

1. Run python tracker.py to see your first task
2. Open AGENT_MASTERY_CHECKLIST.md for the ISSUE-001 spec
3. Create agents/level_1/01_hello_agent.py
4. Run python tracker.py complete 1 when done!

---

📚 Curriculum Overview

🥉 Level 1: Foundations (1,100 XP)

Learn the core building blocks

• Agent invocation patterns
• Creating and using tools (@tool decorator)
• Memory and state management
• Structured output with Pydantic
• Multi-turn conversations

🥈 Level 2: Advanced Reasoning (1,800 XP)

Master prompt engineering strategies

• Chain-of-Thought (step-by-step reasoning)
• Self-Reflection (critique and improve)
• Plan-and-Execute (user approval workflows)
• ReAct (Thought → Action → Observation)
• Few-Shot learning (example-based)

🥇 Level 3: RAG & Knowledge (2,350 XP)

Build knowledge-augmented agents

• Vector stores and embeddings
• Chunking strategies
• Retrieval patterns (similarity, hybrid, MMR)
• Reranking for precision
• Self-RAG and Corrective RAG

💎 Level 4: Multi-Agent Systems (3,100 XP)

Coordinate multiple agents

• Sequential pipelines
• Conditional routing
• Parallel execution
• Supervisor patterns
• Adversarial collaboration

💎 Level 5: Production Ready (3,100 XP)

Ship agents to production

• Human-in-the-loop approval
• Error handling and resilience
• Streaming responses
• Cost management
• Observability and monitoring

👑 Level 6: Mastery (2,500 XP)

Prove your expertise

• Combine 5+ patterns
• Create decision guides
• Teach others
• Innovate new patterns

---

📁 Repository Structure

ai-agent-mastery/
│
├── 🎮 tracker.py             # CLI progress tracker (run this!)
├── 🌐 dashboard.py           # Web dashboard (Gradio)
├── 📊 progress.json          # Your progress data (auto-managed)
│
├── 📋 STATUS.md              # Manual progress view (optional)
├── 📖 AGENT_MASTERY_CHECKLIST.md  # Full curriculum + reference guides
│
├── 📁 tasks/                 # Detailed task specifications
│   ├── level_1/             # Each task = one file with full spec
│   ├── level_2/
│   ├── level_3/
│   ├── level_4/
│   ├── level_5/
│   └── level_6/
│
├── 📁 agents/                # Your implementations go here
│   ├── level_1/
│   ├── level_2/
│   └── ...
│
├── 📁 .github/               # ⚠️ IMPORTANT: Coding rules & instructions
│   ├── instructions/
│   │   ├── python.instructions.md
│   │   └── tests.instructions.md
│   └── coding-rules-compact.md
│
├── 📁 tests/                 # Test your implementations
└── 📁 utils/                 # Shared utilities

---

⚠️ Important: Instruction Files

These files define coding standards for AI-assisted development

Why Instructions Matter

When using AI coding assistants (GitHub Copilot, Claude, Cursor), instruction files ensure:

1. Consistent Code Style - All code follows the same patterns
2. Best Practices - Type hints, docstrings, error handling
3. Project-Specific Rules - LangChain patterns, testing standards
4. Quality Gates - AI won't generate subpar code

Key Instruction Files

File	Purpose
.github/instructions/python.instructions.md	Python coding standards, type hints, docstrings
.github/instructions/tests.instructions.md	Testing patterns, pytest conventions
.github/coding-rules-compact.md	Quick reference for all coding rules

How They Work

You write: "Create a tool that converts temperatures"

Without instructions:
def convert(t):
    return t * 9/5 + 32  # No types, no docs, no error handling

With instructions:
@tool
def convert_temperature(
    value: float,
    from_unit: Literal["celsius", "fahrenheit"],
    to_unit: Literal["celsius", "fahrenheit"]
) -> str:
    """
    Convert temperature between Celsius and Fahrenheit.
    
    Args:
        value: The temperature value to convert
        from_unit: Source unit ('celsius' or 'fahrenheit')
        to_unit: Target unit ('celsius' or 'fahrenheit')
    
    Returns:
        Formatted string with conversion result
    
    Raises:
        ValueError: If units are invalid or the same
    """
    ...

---

📊 Progress Tracking

Gamified Learning

Rank	XP Required	Level
🥉 Bronze	0 - 2,000	1-2
🥈 Silver	2,000 - 5,000	2-3
🥇 Gold	5,000 - 8,000	3-4
💎 Diamond	8,000 - 12,000	4-5
👑 Master	12,000+	6

Dynamic Tracker

CLI (Beautiful terminal UI):

python tracker.py

╭─────────────────────────────╮
│ 🤖 AI AGENT MASTERY         │
│ 0 / 13,950 XP  •  🥉 Bronze │
╰─────────────────────────────╯
╭────────────────────────┬────────────────────────────────┬───────┬────╮
│ Level                  │ Progress                       │ Tasks │ XP │
├────────────────────────┼────────────────────────────────┼───────┼────┤
│ L1 Foundations         │ ░░░░░░░░░░░░░░░░░░░░           │  0/6  │  0 │
│ L2 Advanced Reasoning  │ ░░░░░░░░░░░░░░░░░░░░           │  0/6  │  0 │
...
╰────────────────────────┴────────────────────────────────┴───────┴────╯

Web Dashboard (Gradio):

python dashboard.py   # Opens http://localhost:7860

Commands

python tracker.py              # Show dashboard
python tracker.py complete 1   # Mark #001 complete → +100 XP
python tracker.py complete 2   # Mark #002 complete → +150 XP
python tracker.py next         # Show next task details
python tracker.py reset        # Start over

---

📚 Reference Guides

The AGENT_MASTERY_CHECKLIST.md includes comprehensive reference sections:

🎯 Prompt Engineering Strategies

• When to use Zero-Shot vs Few-Shot
• Chain-of-Thought patterns
• Self-Consistency techniques
• ReAct implementation
• Anti-patterns to avoid

📚 RAG Strategies

• Chunking strategies (fixed, semantic, parent-child)
• Embedding model comparison
• Vector store selection guide
• Retrieval patterns (similarity, hybrid, MMR)
• Reranking decision matrix
• RAG architecture patterns (Naive, Agentic, Self, Corrective)

---

🛠️ Tech Stack

Component	Technology
LLM Framework	LangChain 0.2+
Agent Framework	LangGraph
Vector Store	Chroma (dev), Pinecone (prod)
Embeddings	OpenAI, or open-source alternatives
Memory	SQLite (dev), PostgreSQL (prod)
Monitoring	LangSmith
Testing	pytest

---

🤝 Contributing

Contributions welcome! Please:

1. Follow the coding standards in .github/instructions/
2. Add tests for new features
3. Update documentation
4. Submit a PR with clear description

---

📖 Resources

Official Documentation

• LangChain Docs
• LangGraph Docs
• LangSmith

Papers & Research

• ReAct: Synergizing Reasoning and Acting
• Chain-of-Thought Prompting
• Self-RAG

Community

• LangChain Discord
• Twitter/X #langchain

---

📜 License

MIT License - feel free to use this curriculum for learning, teaching, or building products.

---

Ready to become an AI Agent Master?

📋 Check Your Status → 🎯 Start Task 002

---

Built with ❤️ for the AI developer community