🧰 धडा 03 — Tools: agent चे हात

📍 तुम्ही इथे आहात: 8 पैकी धडा 03 · मागे: lesson-02-the-loop · पुढे: lesson-04-memory

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

धडे 01–02, आणि ACT ठोका तपशीलात: tool म्हणजे नेमके काय, model ते कसे निवडते, आणि तुमचा agent चालेल की नाही हे ठरवणारे design चे नियम.

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

कर्ता-विद्यार्थी एक छोटा toolbelt 🧰 बाळगतो, आणि प्रत्येक tool वर विद्यार्थ्यासाठीच लिहिलेले एक लेबल असते:

lookup {"topic": …} — शाळेच्या office ला विचारा calc {"expression": …} — calculator write_note {"text": …} — वर्गाच्या डायरीत लिहा (गोष्टी बदलते!)

पट्ट्याबद्दल तीन तथ्ये:

लेबले म्हणजे अर्धी बुद्धिमत्ता. model tools ची नावे, वर्णने आणि argument चे स्वरूप वाचूनच tools निवडते. अस्पष्ट लेबल → चुकीचे tool, चुकीचे arguments, किंवा call च नाही. tool ची वर्णने लिहिणे म्हणजे screwdriver घेऊन केलेले prompt engineering.
model कधीच tool ला हात लावत नाही. ते एक request लिहिते ("calc: ceil(23/3)"); harness ते चालवतो आणि निकाल परत देतो — MCP शाळा L02 मधलीच model-proposes/harness-disposes विभागणी. म्हणूनच…
tools चे reads आणि writes असे दोन भाग पडतात. lookup कुणालाही इजा करू शकत नाही — त्याला मोकळे चालू द्या. write_note जग बदलते — आपल्या code मध्ये त्यावर "writes": True असे लेबल आहे आणि harness त्याला GATE करतो (धडा 05). आपल्या tools ची या दोन गटांत विभागणी करणे हाच पहिला security review आहे, एका मिनिटात झालेला.

आणि मोठ्या प्रमाणावर पट्टे येतात कुठून? MCP — standard socket (पूर्णपणे वेगळी शाळा): servers जोडा, आणि त्यांची tools आपोआप पट्ट्यावर दिसतात.

🗺️ आकृती

flowchart LR
    subgraph belt["🧰 the toolbelt (agent.py TOOLS)"]
        r1["lookup - READ<br/>'ask the school office'"]
        r2["calc - READ<br/>'safe math, ceil() allowed'"]
        w1["write_note - WRITE 🚧<br/>'changes the diary!'"]
    end
    m["🧠 model - picks by<br/>READING the labels"]
    h["🏫 harness - executes<br/>(gates the writes)"]
    world["🌍 the world"]
    m -->|"1 writes a request"| h -->|"2 runs the tool"| world
    world -->|"3 observation → desk"| m
    belt -.->|"labels shown to the model"| m

❓ काय

Tool = name + description + argument schema + implementation. आपल्या TOOLS dict मध्ये नेमके हेच आहे (आणि writes flag — हा pattern उचलाच).
प्रत्यक्षात महत्त्वाचे design नियम: एका tool ला एकच काम; स्पष्ट, मर्यादित arguments (मोकळ्या strings पेक्षा enums चांगले); model वापरू शकेल असा थोडक्यात text परत करा (एक screen भर, database चा ढीग नाही — desk लहान आहे, AI L08); errors वाचता येतील अशा strings म्हणून ("errors are data").
calc बचावात्मक implementation दाखवते: AST वरून चालणारा evaluator जो फक्त numbers आणि ceil() ला परवानगी देतो, बाकी काहीच नाही — कारण tool चा INPUT अशा model कडून येतो जे गोंधळू शकते किंवा ज्यावर injection होऊ शकते (धडा 06). model ने लिहिलेल्या गोष्टीवर कधीही eval() करू नका. कधीच नाही.
done pseudo-tool: थांबणे हीसुद्धा फक्त आणखी एक लेबल असलेली निवड.

🤔 का

agent ची गुणवत्ता model च्या गुणवत्तेपेक्षा tools च्या गुणवत्तेवर जास्त अवलंबून असते. पाच नेटक्या, चांगली लेबले असलेल्या, मर्यादित व्याप्तीच्या tools सह साधारण model, do_stuff(anything) असलेल्या frontier model ला मागे टाकते. तुमचा agent धडपडत असेल, तर त्याच्या tool labels मोठ्याने वाचा — कोणते निवडायचे ते तुम्हालाच कळत नसेल, तर model लाही कळणार नाही.

🧪 करून पाहा

python3 agent/agent.py --drive
# your move> calc {"expression": "ceil((12+11)/3)"}
# your move> calc {"expression": "__import__('os')"}     ← try to break it 😈

दुसरा call सुरक्षितपणे अयशस्वी होतो — का ते पाहण्यासाठी agent.py मधले _safe_eval वाचा. मग कागदावर तुमच्या कामासाठी toolbelt design करा: पाच tools, प्रत्येकी एक ओळ, READ किंवा WRITE अशी खूण केलेली. तो दस्तऐवज म्हणजे agent spec चा 80% भाग.

⏭️ पुढे

ठोक्यांमधले desk: memory — scratchpads, context च्या मर्यादा, आणि लांब कामांना डायरी का लागते.

git checkout lesson-04-memory

🧰 Lesson 03 — Tools: the agent's hands

📍 You are here: Lesson 03 of 8 · Previous: lesson-02-the-loop · Next: lesson-04-memory

📦 What's in this branch

Lessons 01–02, plus the ACT beat in detail: what a tool IS, how the model chooses one, and the design rules that decide whether your agent works.

🧒 Explain like I'm 5

The doer-student carries a small toolbelt 🧰, and each tool has a label written FOR the student:

lookup {"topic": …} — ask the school office calc {"expression": …} — the calculator write_note {"text": …} — write in the class diary (changes things!)

Three facts about the belt:

The labels are half the intelligence. The model picks tools by READING their names, descriptions and argument forms. Vague label → wrong tool, wrong arguments, or no call at all. Writing tool descriptions is prompt engineering with a screwdriver.
The model never touches the tool. It writes a request ("calc: ceil(23/3)"); the harness executes and returns the result — the same model-proposes/harness-disposes split as MCP school L02. Which is why…
Tools split into reads and writes. lookup can't hurt anyone — let it flow. write_note changes the world — it's labeled "writes": True in our code and the harness GATES it (lesson 05). Sorting your tools into these two buckets is the first security review, done in one minute.

And where do belts come from at scale? MCP — the standard socket (the whole other school): plug in servers, and their tools appear on the belt automatically.

🗺️ Diagram

flowchart LR
    subgraph belt["🧰 the toolbelt (agent.py TOOLS)"]
        r1["lookup - READ<br/>'ask the school office'"]
        r2["calc - READ<br/>'safe math, ceil() allowed'"]
        w1["write_note - WRITE 🚧<br/>'changes the diary!'"]
    end
    m["🧠 model - picks by<br/>READING the labels"]
    h["🏫 harness - executes<br/>(gates the writes)"]
    world["🌍 the world"]
    m -->|"1 writes a request"| h -->|"2 runs the tool"| world
    world -->|"3 observation → desk"| m
    belt -.->|"labels shown to the model"| m

❓ What

Tool = name + description + argument schema + implementation. Our TOOLS dict has exactly these (plus the writes flag — steal that pattern).
Design rules that matter in practice: one job per tool; explicit, constrained arguments (enums beat free strings); return CONCISE text the model can use (a screenful, not a database dump — the desk is small, AI L08); errors as readable strings ("errors are data").
calc shows defensive implementation: an AST-walking evaluator that allows numbers and ceil() and nothing else — because tool INPUT comes from a model that can be confused or injected (lesson 06). Never eval() what a model wrote. Never.
The done pseudo-tool: termination as just another labeled choice.

🤔 Why

Agent quality tracks tool quality more than model quality. A mediocre model with five crisp, well-labeled, well-scoped tools beats a frontier model with do_stuff(anything). When your agent flails, read it your tool labels out loud — if YOU wouldn't know which to pick, neither does the model.

🧪 Try it

python3 agent/agent.py --drive
# your move> calc {"expression": "ceil((12+11)/3)"}
# your move> calc {"expression": "__import__('os')"}     ← try to break it 😈

The second call fails safely — read _safe_eval in agent.py to see why. Then design, on paper, the toolbelt for YOUR job: five tools, one line each, marked READ or WRITE. That artifact is 80% of an agent spec.

⏭️ Next

The desk between the beats: memory — scratchpads, context limits, and why long tasks need a diary.

git checkout lesson-04-memory

← Previousthe loop Next →memory

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