🔬 धडा 07 — agent बनवा: 130 प्रामाणिक ओळी

📍 तुम्ही इथे आहात: 8 पैकी धडा 07 · मागे: lesson-06-failures · पुढे: lesson-08-patterns

📦 या ब्रँचमध्ये काय आहे

धडे 01–06, आणि agent/agent.py चे मार्गदर्शित वाचन — या course मधली प्रत्येक संकल्पना, एका ओळ क्रमांकावर सापडणारी.

🧒 5 वर्षांच्या मुलाला समजावल्यासारखे

file उघडा. तीन क्रमांकित विभाग, course शी तंतोतंत जुळणारे:

🧰 THE TOOLS — पट्टा (L03): SCHOOL_DB (जग), _safe_eval (अवघड input विरुद्ध कठोर केलेले tool — L05 नियम 3), तीन tool functions, आणि TOOLS registry जिथे प्रत्येक entry सोबत help (model साठीचे लेबल) आणि writes (gate चा flag) असतो. लक्षात घ्या, done ही फक्त आणखी एक लेबल असलेली निवड आहे.
🧠 THE BRAINS — THINK ठोका, बदलता येणारा:
- ScriptedBrain — एक खेळण्यातला planner (scratchpad वरची if-ची शिडी) ज्यामुळे demo API key शिवाय चालतो. त्याची docstring हे course चे सर्वात मोठे गुपित आहे: या class च्या जागी एक LLM call ठेवा — "हे goal + pad + tool labels, पुढे काय?" — आणि बाकी सगळे तसेच राहते. loop हाच agent आहे; model हा एक भाग आहे.
- HumanBrain — --drive mode: तुम्ही, type करत. LLM च्या जागी माणूस बसू शकतो यावरूनच कळते की LLM नेमके काय देते: निर्णय, बाकी काहीच नाही.
🔁 THE LOOP + GUARDRAILS — run(): for step in range(MAX_STEPS) curfew (L05 नियम 1), छापलेले THINK/ACT, done मधून बाहेर पडणे, अनोळखी tool आणि errors ना observations म्हणून हाताळणे ("errors are data"), write gate if TOOLS[name]["writes"] and not auto_approve (L05 नियम 2 — file मधले सर्वात मौल्यवान if), आणि scratchpad.append(...) — एका ओळीत memory (L04).

~130 ओळी. framework नाही. तुम्हाला भेटणारा प्रत्येक agent framework म्हणजे हीच file, जास्त विशेषणांसह.

🗺️ आकृती

flowchart TB
    subgraph file["agent/agent.py — the map"]
        t["1 🧰 TOOLS<br/>belt + labels + writes-flags<br/>+ a hardened calc"]
        b["2 🧠 BRAINS (swappable!)<br/>ScriptedBrain: toy planner<br/>HumanBrain: --drive<br/>← an LLM call slots HERE"]
        l["3 🔁 run() loop<br/>MAX_STEPS curfew · write gate 🚧<br/>errors-as-observations ·<br/>scratchpad.append = memory"]
    end
    t --> l
    b --> l
    l --> out["✅ outcome + full printed log 🧾"]

❓ काय (उचलण्याजोगे तपशील)

प्रत्येक tool वरचा writes flag — एका field चे permission model, जे खरी policy लागण्याआधी आश्चर्यकारकरीत्या खूप दूरपर्यंत पुरते.
interface म्हणून Brain (decide(goal, scratchpad) → (name, args, thought)) — यामुळे agent test करता येतो (brain script करा!) आणि upgrade करता येतो (loop ला हात न लावता models बदला).
evals साठी निश्चित जग — SCHOOL_DB ठरलेले आहे, म्हणून परिणाम assert करता येतात (धडा 06 चे eval त्याविरुद्धच चालले).
MCP कुठे बसते: TOOLS dict च्या जागी "जोडलेल्या MCP servers कडून tools ची यादी" ठेवा (MCP शाळा L07 चा client!) आणि पट्टा plug-and-play होतो. या दोन शाळा म्हणजे एकाच यंत्राचे दोन अर्धे भाग.

🤔 का

Frameworks चांगले आहेत — पण हे mental model नसताना त्यांना debug करणे म्हणजे पुरातत्त्व संशोधन. 130 ओळी वाचल्यावर तुम्हाला कळते की LangGraph/CrewAI/काहीही यांचा प्रत्येक थर कशासाठी आहे, कोणता knob कोणत्या संकल्पनेशी जुळतो, आणि — सर्वात मौल्यवान — एखाद्या कामासाठी तुम्हाला काय लागत नाही. चांगली tools आणि gates असलेले साधे loops ship होतात.

🧪 करून पाहा — तीन upgrades, प्रत्येकी ~5 ओळी

# A) new tool: add "list_notes" (READ) that returns note.txt contents.
#    → belt entry + function. Rerun --drive and call it.
# B) loop detection (L06 #2): in run(), before acting —
#    if scratchpad and f"[{name} {json.dumps(args)}]" in scratchpad[-1]:
#        observation = "you just did exactly that — try something else"
# C) real brain: replace ScriptedBrain.decide with an API call that
#    sends goal + scratchpad + tool helps and parses "name {json}".
#    (~15 lines with any LLM SDK — the harness doesn't change at all.)
python3 agent/agent.py --drive

किमान upgrade A ship करा. आता तुम्ही "agent framework वापरलेली" व्यक्ती नाही — तुम्ही असा framework लिहू शकणारी व्यक्ती आहात. 🔬

⏭️ पुढे

शेवटचा भाग: एकेकटे loops एकत्र येऊन patterns कसे बनतात — planners, critics, teams, human-in-the-loop — आणि agent अजिबात कधी वापरू नये.

git checkout lesson-08-patterns

🔬 Lesson 07 — Build an agent: 130 honest lines

📍 You are here: Lesson 07 of 8 · Previous: lesson-06-failures · Next: lesson-08-patterns

📦 What's in this branch

Lessons 01–06, plus the guided read of agent/agent.py — every concept from this course, findable at a line number.

🧒 Explain like I'm 5

Open the file. Three numbered sections, exactly matching the course:

🧰 THE TOOLS — the belt (L03): SCHOOL_DB (the world), _safe_eval (a tool hardened against tricky input — L05 rule 3), three tool functions, and the TOOLS registry where every entry carries help (the label FOR the model) and writes (the gate flag). Notice done is just another labeled choice.
🧠 THE BRAINS — the THINK beat, swappable:
- ScriptedBrain — a toy planner (an if-ladder over the scratchpad) so the demo runs with no API key. Its docstring is the course's biggest secret: replace this class with one LLM call — "here's the goal + pad + tool labels, what next?" — and everything else stays. The loop is the agent; the model is a part.
- HumanBrain — --drive mode: you, typing. The fact that a human slots in where the LLM goes tells you exactly what an LLM contributes: decisions, nothing else.
🔁 THE LOOP + GUARDRAILS — run(): the for step in range(MAX_STEPS) curfew (L05 rule 1), THINK/ACT printed, the done exit, unknown-tool and error handling as observations ("errors are data"), the write gate if TOOLS[name]["writes"] and not auto_approve (L05 rule 2 — the most valuable if in the file), and scratchpad.append(...) — the memory (L04) in one line.

~130 lines. No framework. Every agent framework you'll ever meet is this file with more adjectives.

🗺️ Diagram

flowchart TB
    subgraph file["agent/agent.py — the map"]
        t["1 🧰 TOOLS<br/>belt + labels + writes-flags<br/>+ a hardened calc"]
        b["2 🧠 BRAINS (swappable!)<br/>ScriptedBrain: toy planner<br/>HumanBrain: --drive<br/>← an LLM call slots HERE"]
        l["3 🔁 run() loop<br/>MAX_STEPS curfew · write gate 🚧<br/>errors-as-observations ·<br/>scratchpad.append = memory"]
    end
    t --> l
    b --> l
    l --> out["✅ outcome + full printed log 🧾"]

❓ What (details worth stealing)

The writes flag on every tool — a one-field permission model that scales surprisingly far before you need real policy.
Brain as an interface (decide(goal, scratchpad) → (name, args, thought)) — makes the agent testable (script a brain!) and upgradeable (swap models without touching the loop).
Deterministic world for evals — SCHOOL_DB is fixed, so outcomes are assertable (lesson 06's eval ran against it).
Where MCP snaps in: replace the TOOLS dict with "list tools from connected MCP servers" (MCP school L07's client!) and the belt becomes plug-and-play. The two schools are two halves of one machine.

🤔 Why

Frameworks are fine — but debugging one without this mental model is archaeology. After reading 130 lines you know what every layer of LangGraph/CrewAI/whatever is FOR, which knob maps to which concept, and — most valuable — what you don't need for a given job. Simple loops with good tools and gates ship.

🧪 Try it — three upgrades, ~5 lines each

# A) new tool: add "list_notes" (READ) that returns note.txt contents.
#    → belt entry + function. Rerun --drive and call it.
# B) loop detection (L06 #2): in run(), before acting —
#    if scratchpad and f"[{name} {json.dumps(args)}]" in scratchpad[-1]:
#        observation = "you just did exactly that — try something else"
# C) real brain: replace ScriptedBrain.decide with an API call that
#    sends goal + scratchpad + tool helps and parses "name {json}".
#    (~15 lines with any LLM SDK — the harness doesn't change at all.)
python3 agent/agent.py --drive

Ship upgrade A at minimum. You're no longer a person who "used an agent framework" — you're a person who could write one. 🔬

⏭️ Next

The finale: how single loops combine into patterns — planners, critics, teams, human-in-the-loop — and when NOT to use an agent at all.

git checkout lesson-08-patterns

← Previousfailures Next →patterns

This page is the lesson's README from the lesson-07-build-an-agent branch, shown here so the whole School stays on one site. Code files open on GitHub at the same branch.