📋 Learn AI Agents the school way

Chatbots answer; agents achieve. This school teaches the loop that makes the difference — and ships it: a real agent in the repo, ~130 lines of pure Python, zero dependencies, no API key. Run it, drive it, break it, eval it, read every line.

🔁 think→act→observe🧰 tools & belts 📔 memory🚧 guardrails 💥 failure modes👯 5 patterns

🔁 Part 1 — THE MACHINE (1–5)

  • answers vs outcomes — the doer with a hall pass 🎫
  • the loop: think → act → observe, on repeat
  • the belt: labels are half the intelligence 🧰
  • the pad, the small desk — and the field-trip rules 🚧

💥 Part 2 — REALITY (6–8)

  • five failure modes + the evals that catch them 📊
  • read the agent whole: 130 honest lines 🔬
  • patterns: planners, critics, teams, human gates 👯
  • …and the rarest skill: knowing when NOT to 🙅
# the 60-second wow — a goal becomes an outcome:
git clone https://github.com/BaluRaut/learn-agents-school.git && cd learn-agents-school
python3 agent/agent.py            # a scripted brain runs the picnic errand
python3 agent/agent.py --drive    # YOU are the brain: pick every action

🗺️ The big picture — one diagram, both worlds

Click for the 4K version.

The big picture: the agent machine (loop, tools, memory, guardrails) and reality (failures, evals, patterns)

🎓 The 8 lessons

One git branch = one idea; branch 05 contains lessons 01–05. Deep-dive companion to the AI course's lesson 11 — and the MCP school supplies the tool belt. Curious how we got here and where it goes? Read before · why · agentic · future.

1

📋 What is an agent

Answers vs outcomes — the reciter vs the doer with a hall pass.lesson-01-what-is-an-agentRead lesson →See the diagram ↗
2

🔁 The loop

Think → act → observe — how you run errands, and how agents do.lesson-02-the-loopRead lesson →See the diagram ↗
3

🧰 Tools

The belt: labels are half the intelligence; reads flow, writes gate.lesson-03-toolsRead lesson →See the diagram ↗
4

📔 Memory

Scratchpad, the small desk, compaction — and the homework diary.lesson-04-memoryRead lesson →See the diagram ↗
5

🚧 Guardrails

Field-trip rules: curfew, write gates, hardened tools, full logs.lesson-05-guardrailsRead lesson →See the diagram ↗
6

💥 Failure modes

Confidently wrong, with momentum — five ways it breaks, and evals.lesson-06-failuresRead lesson →See the diagram ↗
7

🔬 Build an agent

Read agent.py whole: 130 lines, every concept at a line number.lesson-07-build-an-agentRead lesson →See the diagram ↗
8

🌍 Agent patterns

Planners, critics, teams, human gates — and when NOT to.lesson-08-patternsRead lesson →See the diagram ↗
👯 The showcase: 5 agent patterns — solo doer, planner+executor, critic loop, human-in-the-loop, the team — each with a numbered flow diagram AND a full sequence diagram.

📐 The lesson diagrams — follow the numbers

Teal = the machine, red = reality. Lesson 02 is a sequence diagram — the loop in its natural notation. Also on a standalone page.

1 📋 What is an agent

Answers vs outcomes — the reciter vs the doer with a hall pass.

🗣️ chatbot — answers'how many pizzas?' →'probably 6-8?' — words,from memory, maybe wrong1📋 agent — outcomes🧠 model in a LOOPthink→act→observe🧰 tools + 🎫 hall passlookup · calc · write✅ counted 23 kids, computed 8 pizzas,SAVED the plan — the job is DONE2same brain — the difference is the loop and the pass · run it: python3 agent/agent.py3

Read full lesson 01 →

2 🔁 The loop

Think → act → observe — how you run errands, and how agents do.

🧠 brain🏫 harness🌍 worldthe THINK beat is next-token prediction; the loop is a conversation with realityTHINK 💭 'need the class size' — reasoning as text1ACT 🧰 lookup {"topic":"class 3A"}2executes the tool3'Class 3A has 12 students.'4OBSERVE 👀 → onto the scratchpad5🔁 repeat, smarter each beat — until done {answer} (or MAX_STEPS 🕐)

Read full lesson 02 →

3 🧰 Tools

The belt: labels are half the intelligence; reads flow, writes gate.

🧰 the belt (TOOLS)lookup — READ · 'ask the office'calc — READ · 'safe math'write_note — WRITE 🚧 gated!1🧠 modelpicks by READING the labels —labels are half the intelligence2🏫 harnessexecutes · gates writes ·returns observations3observation → the desknever eval() what a model wrote — see _safe_eval: an allowlist, not trust 🔒

Read full lesson 03 →

4 📔 Memory

Scratchpad, the small desk, compaction — and the homework diary.

🪑 the desk — finite!📋 goal + to-do📔 scratchpad:[lookup 3A]→12 kids…💭 THINK reads all of it, every beat1🗜️ compaction10 jottings → 1 summary line, when the desk fills2📁 durable memory OUTSIDEwrite_note / files / DB / RAG over past runs3'it forgot step 3' and 'it falls apart after 30 steps' are BOTH desk problems — now you know the fix first

Read full lesson 04 →

5 🚧 Guardrails

Field-trip rules: curfew, write gates, hardened tools, full logs.

🔁 the loop wants to run forever,touch everything, trust every input🕐 MAX_STEPS + budgetsbounded loops, bounded bills1🚧 write gates — reads flow,writes wait for a human [y/N]2🔒 hardened tools + scoped credsallowlists, least privilege (AWS L03)3🧾 full logs — every beat,numbered, replayable4📦 sandboxes — blast radius= one container 🍱5

Read full lesson 05 →

6 💥 Failure modes

Confidently wrong, with momentum — five ways it breaks, and evals.

💥 compounding: wrong fact at step 2→ polished wrong answer at step 91🔄 loops: the same act,again and again and again2📝 injection: instructionshiding inside tool results3🎯 goal drift:'helpful' side quests4🙋 fake done: declared success,no actual outcome5📊 EVALS — scored scenarios, run on every changeoutcome checks · step budgets · gate audits · a deterministic world to assert against

Read full lesson 06 →

7 🔬 Build an agent

Read agent.py whole: 130 lines, every concept at a line number.

1 🧰 TOOLSthe belt: labels + writes-flags+ _safe_eval (hardened)SCHOOL_DB = a deterministicworld — evals assert against it12 🧠 BRAINS — swappableScriptedBrain: toy plannerHumanBrain: --drive (you!)← ONE LLM call slots here;the harness never changes23 🔁 run() — the loopMAX_STEPS curfew 🕐write gate 🚧 (one if!)errors-as-observationsscratchpad.append = memoryprints every beat 🧾3~130 lines, no framework — every framework is this file with more adjectives

Read full lesson 07 →

8 🌍 Agent patterns

Planners, critics, teams, human gates — and when NOT to.

🙅 steps fixed?→ a SCRIPT1🗣️ one answer?→ one model call2🧍 path varies by discovery?→ SOLO agent + tools(start here!)3🗺️ long/structured? + planner🧑‍🏫 quality-critical? + critic4🚧 irreversible steps? + human gates(always — drafts flow, signatures gate)5👯 truly parallel? + a team —with a foreman & checkable artifacts6every pattern = the same loop, wrapped — the best architects say 'this doesn't need an agent' weekly 🙅

Read full lesson 08 →

Start Lesson 01 → 👯 The 5 patterns ⏮️ Before · why · agentic · future 📐 All 8 lesson diagrams 🧪 Quiz 🗓️ Study plan 🔌 The MCP school