AI एजेंट्स बनानामध्यमपाठ 1977 मिनट का पाठ

अच्छे टूल्स डिज़ाइन करना

मॉडल आपके टूल्स का इस्तेमाल सिर्फ़ उतने ही अच्छे से कर सकता है जितने अच्छे से आप उनके बारे में बताते हैं। टूल्स को नाम देना, उनका विवरण लिखना और उन्हें सही आकार देना सीखें, ताकि मॉडल सही टूल चुने और गलतियों से उबर सके।

✦ ट्यूटर से पूछें 🧪 लैब · 30 min 📝 पाठ का टेस्ट

स्पीड

पाठ वीडियो में

60 सेकंड में

अच्छे टूल्स डिज़ाइन करना

मॉडल आपके टूल्स का इस्तेमाल सिर्फ़ उतने ही अच्छे से कर सकता है जितने अच्छे से आप उनके बारे में बताते हैं। टूल्स को नाम देना, उनका विवरण लिखना और उन्हें सही आकार देना सीखें, ताकि…

1/4

आसान शब्दों में

एक ऐसे टूलबॉक्स की कल्पना करें जिसमें हर टूल भूरे कागज़ में लिपटा हो और उस पर "चीज़" लिखा हो। आप हर बार गलत टूल ही चुनेंगे। "चश्मे के लिए छोटा पेचकश" जैसे साफ़ लेबल काम को आसान बना देते हैं। टूल्स चुनते समय मॉडल के सामने भी यही समस्या होती है: वह सिर्फ़ वही लेबल देख पाता है जो आप लिखते हैं।

मॉडल आपके टूल का कोड कभी नहीं देखता। वह सिर्फ़ नाम, विवरण और पैरामीटर स्कीमा देखता है। ये चंद लाइनें एक यूज़र इंटरफ़ेस हैं, और यहाँ यूज़र खुद मॉडल है। एक एजेंट में किया जा सकने वाला सबसे बड़ा सुधार अक्सर अच्छा टूल डिज़ाइन ही होता है।

अच्छे टूल्स के लिए पाँच नियम

नियम	कमज़ोर	बेहतर
साफ़ नाम, पहले क्रिया	`data`, `helper2`	`search_orders`, `get_order_status`
विवरण बताता है कि इसका इस्तेमाल कब करना है, और कब नहीं	"ऑर्डर लाता है।"	"आईडी से कोई एक ऑर्डर ढूँढें। तब इस्तेमाल करें जब यूज़र कोई ऑर्डर आईडी दे। नाम या तारीख से खोजने के लिए search_orders का इस्तेमाल करें।"
सीमित दायरा, हर टूल का सिर्फ़ एक काम	`run_sql(query)`	`get_order_status(order_id)`
सरल और टाइप्ड पैरामीटर	एक फ़्री-टेक्स्ट `input` स्ट्रिंग	`order_id` (स्ट्रिंग, ORD-123456 जैसा पैटर्न), `limit` (पूर्णांक, 1 से 20)
ऐसे परिणाम जो छोटे और काम के हों	पूरी 300 फ़ील्ड वाली डेटाबेस पंक्ति	सिर्फ़ वही फ़ील्ड जिनकी काम के लिए ज़रूरत है, एक छोटे JSON ऑब्जेक्ट में

सीमित दायरे वाले टूल्स ज़्यादा सुरक्षित और आसान होते हैं

run_sql या run_shell जैसा खुला टूल कुछ भी कर सकता है, इसलिए मॉडल को इसे बिल्कुल सही लिखना होगा, और मॉडल के इनपुट को कंट्रोल करने वाला कोई हमलावर भी इससे कुछ भी करवा सकता है। get_order_status(order_id) जैसा सीमित टूल सिर्फ़ एक ही काम कर सकता है। मॉडल के लिए इसका इस्तेमाल करना आसान होता है और आपके लिए इसे सुरक्षित रखना बहुत आसान होता है। यह टूल्स पर लागू होने वाला least privilege का सिद्धांत है।

ऐसे एरर जिन पर मॉडल काम कर सके

जब कोई टूल फ़ेल होता है, तो उसका एरर मैसेज मॉडल के पास जाता है। एरर उसी पाठक को ध्यान में रखकर लिखें: बताएं कि क्या गलत हुआ और आगे क्या कोशिश करनी है।

ऐसे एरर जो मॉडल के काम नहीं आ सकते

Error 500
KeyError: 'id'
Invalid input
200 लाइनों का स्टैक ट्रेस

ऐसे एरर जिन्हें मॉडल ठीक कर सकता है

ORD-12345 नाम का कोई ऑर्डर नहीं है। ऑर्डर आईडी 6 अंकों की होती है, जैसे ORD-123456।
order_id मौजूद नहीं है। यूज़र से इसके बारे में पूछें।
limit 1 से 20 के बीच होनी चाहिए; आपने 500 भेजा है।
सर्विस व्यस्त है। एक बार फिर कोशिश करें; अगर यह फ़ेल हो जाए, तो यूज़र को बताएं।

रीड टूल्स और राइट टूल्स

टूल्स को दो तरह में बाँटें। रीड टूल्स सिर्फ़ डेटा देखते हैं: search, get, list। राइट टूल्स दुनिया में बदलाव करते हैं: send, pay, delete, book, update। इनके साथ अलग तरह से पेश आएं।

रीड टूल्स को आम तौर पर बिना पूछे चलाया जा सकता है। फिर भी उन्हें एक्सेस सीमाओं की ज़रूरत होती है (किस यूज़र का डेटा?)।
राइट टूल्स गिने-चुने और सीमित दायरे वाले होने चाहिए। जोखिम भरे टूल्स के लिए किसी इंसान से पुष्टि की ज़रूरत होती है।
जहाँ तक संभव हो राइट टूल्स को idempotent बनाएं: एक ही रिक्वेस्ट के साथ उन्हें दो बार कॉल करने का वही असर होता है जो एक बार कॉल करने पर होता है। इसका एक आम तरीका idempotency key है, यानी हर रिक्वेस्ट के लिए एक यूनीक आईडी, ताकि दोबारा कोशिश करने पर दो बार रिफ़ंड या दो ईमेल न चले जाएं।
किसी राइट टूल को कभी भी उसके नाम से ज़्यादा काम न करने दें। cancel_order को साथ में रिफ़ंड भी नहीं करना चाहिए, ईमेल भी नहीं भेजना चाहिए और अकाउंट भी बंद नहीं करना चाहिए।

A well-described tool, as a JSON-schema style definitionpython

get_order_status = {
    "name": "get_order_status",
    "description": (
        "Look up the delivery status of ONE order by its id. "
        "Use when the user gives an order id like ORD-123456. "
        "Read-only: it never changes the order. "
        "To find orders by date or product, use search_orders instead."
    ),
    "parameters": {
        "type": "object",
        "properties": {
            "order_id": {
                "type": "string",
                "pattern": "^ORD-[0-9]{6}$",
                "description": "Order id, e.g. ORD-123456",
            }
        },
        "required": ["order_id"],
        "additionalProperties": False,
    },
}

नोट

इसके चारों ओर का सटीक रैपर (उदाहरण के लिए इसे parameters कहा जाए या input_schema) अलग-अलग प्रोवाइडर्स में अलग हो सकता है। विचार वही रहते हैं। अपने प्रोवाइडर के मौजूदा डॉक्स देखें।

कितने टूल्स होने चाहिए?

हर टूल का विवरण कॉन्टेक्स्ट में जगह लेता है और मॉडल को गलती करने का एक और मौका देता है। उन थोड़े-से टूल्स से शुरुआत करें जिनकी काम के लिए सच में ज़रूरत है। अगर दो टूल्स में अक्सर भ्रम होता है, तो उन्हें मिला दें, उनके नाम बदल दें, या उनके विवरण में साफ़-साफ़ लिखें कि किसका इस्तेमाल कब करना है।

सावधान रहें

टूल के विवरण ऐसे निर्देश होते हैं जिनका मॉडल पालन करता है। किसी थर्ड-पार्टी सर्वर से आने वाले विवरण में मॉडल को गुमराह करने के लिए छेड़छाड़ की जा सकती है। Tool poisoning and rug pulls देखें, और ऐसे विवरणों की समीक्षा करें जो आपने नहीं लिखे हैं।

यह आज़माएं। काम पर अपने इस्तेमाल किए जाने वाले किसी एक API को देखें। उसका कोई एक एंडपॉइंट चुनें और उसे मॉडल के टूल के रूप में दोबारा लिखें: एक नाम, "कब इस्तेमाल करें" और "किसके लिए इस्तेमाल न करें" के साथ दो लाइन का विवरण, और टाइप्ड पैरामीटर।

और देखें और पढ़ें

लैब

स्कूल लाइब्रेरी एजेंट के लिए तीन टूल परिभाषाएं, स्कीमा, साफ़ एरर और रीड/राइट विभाजन के साथ।

~30 min

समस्या

एक स्कूल लाइब्रेरी ऐसा एजेंट चाहती है जो छात्रों को किताबें ढूँढने और रिज़र्व करने में मदद करे। कागज़ पर या स्टार्टर फ़ाइल में इसके टूल्स डिज़ाइन करें।

search_books, get_book और reserve_book के लिए परिभाषाएं लिखें: नाम, विवरण ("कब इस्तेमाल करें" और "किसके लिए इस्तेमाल न करें" के साथ), और पैरामीटर के लिए एक JSON स्कीमा।
हर टूल को read या write के रूप में मार्क करें। राइट टूल के लिए बताएं कि आप इसे idempotent कैसे बनाएंगे।
ऐसे तीन एरर मैसेज लिखें जो हर टूल लौटा सकता है, ऐसे शब्दों में जिन पर मॉडल काम कर सके।
ऐसे एक टूल का नाम बताएं जिसे आपने एजेंट को न देने का फ़ैसला किया, और क्यों।

शुरुआती कोडjson

{
  "name": "search_books",
  "description": "TODO: what it does. Use when ... Do not use for ...",
  "parameters": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "TODO" },
      "limit": { "type": "integer", "minimum": 1, "maximum": 10 }
    },
    "required": ["query"],
    "additionalProperties": false
  }
}

आपका काम तब पूरा होगा जब

हर विवरण बताता है कि टूल का इस्तेमाल कब करना है और किसी दूसरे टूल का इस्तेमाल कब करना है
पैरामीटर टाइप्ड और सीमित हैं (पैटर्न, न्यूनतम, अधिकतम, आवश्यक)
राइट टूल के पास एक idempotency योजना है, जैसे कि रिज़र्वेशन रिक्वेस्ट आईडी
एरर मैसेज बताते हैं कि क्या गलत हुआ और आगे क्या कोशिश करनी है

कठिन सवाल

उत्तर देखने से पहले ख़ुद जवाब देने की कोशिश करें। अगर आप इनके जवाब दे सकते हैं, तो आप पाठ समझ गए हैं।

Q1जब छात्र सटीक बुक आईडी देता है, तब भी मॉडल बार-बार <code>search_books</code> को कॉल करता है। ऐसे दो उपाय बताएं जिनमें मॉडल को बदलना शामिल न हो।दिखाएं

पहला, विवरणों को बेहतर बनाएं: search_books में लिखें "अगर यूज़र बुक आईडी देता है, तो इसके बजाय get_book का इस्तेमाल करें", और get_book में एक उदाहरण आईडी दें। दूसरा, स्कीमा में आईडी फ़ॉर्मेट को स्पष्ट करें (एक पैटर्न), और संभव हो तो search_books से आईडी की पहचान करवाएं और ऐसा संकेत लौटाएं जैसे "यह एक बुक आईडी लग रही है; get_book का इस्तेमाल करें"। फिर सुधार की पुष्टि करने के लिए दोबारा ट्रेस देखें।

Q2भले ही मॉडल कभी कोई गलती न करे, फिर भी <code>request_id</code> पैरामीटर के साथ "reserve_book" ज़्यादा सुरक्षित क्यों है?दिखाएं

नेटवर्क फेल हो जाते हैं। हो सकता है टूल किताब रिज़र्व कर ले लेकिन जवाब खो जाए, इसलिए आपका लूप दोबारा कोशिश करता है। बिना request id के, दूसरी कॉल एक और रिज़र्वेशन कर देती है। इसके होने पर, सर्वर वही id देखता है और पहला रिज़ल्ट लौटा देता है। यह खतरा सिर्फ मॉडल से ही नहीं, बल्कि retries और timeouts से भी आता है।

जारी रखने के लिए कृपया साइन इन करें।

अक्सर पूछे जाने वाले सवाल

विवरण लंबा होना चाहिए या छोटा?

इतना लंबा कि इन सवालों का जवाब मिल सके: यह क्या करता है, मुझे इसका इस्तेमाल कब करना चाहिए, कब नहीं करना चाहिए, पैरामीटर का क्या मतलब है, और यह क्या लौटाता है? कुछ साफ़-सुथरे वाक्य आम तौर पर सिर्फ़ एक शब्द या पूरे पन्ने दोनों से बेहतर होते हैं।

क्या मॉडल को run_python जैसा सामान्य टूल देना गलत है?

हमेशा नहीं, लेकिन यह बहुत शक्तिशाली और जोखिम भरा होता है। अगर आप ऐसा करते हैं, तो इसे बिना किसी सीक्रेट्स, सीमित नेटवर्क और समय व मेमोरी की सीमाओं वाले sandbox में चलाएं। बिज़नेस से जुड़े ज़्यादातर कामों के लिए, सीमित दायरे वाले कुछ टूल्स ज़्यादा सुरक्षित और भरोसेमंद होते हैं। देखें Sandboxing: the room with no windows।

जब कुछ न मिले तो टूल को क्या लौटाना चाहिए?

एक साफ़, सामान्य परिणाम, जैसे {"orders": [], "note": "No orders in this date range"}। खाली स्ट्रिंग या एरर से मॉडल को लग सकता है कि टूल खराब हो गया है और वह बार-बार कोशिश कर सकता है।

मुझे कैसे पता चलेगा कि कौन से टूल के विवरण मॉडल को भ्रमित कर रहे हैं?

वास्तविक रन के ट्रेस देखें। अगर मॉडल अक्सर गलत टूल कॉल करता है, या छूटे हुए तर्कों के साथ किसी टूल को कॉल करता है, तो उस विवरण पर काम करने की ज़रूरत है। Evaluating and debugging agents पाठ में दिखाया गया है कि इन ट्रेस को कैसे इकट्ठा किया जाए।

पाठ का टेस्ट

5 सवाल। पास होने और इस पाठ को पूरा करने के लिए 3 सही होने चाहिए (60%)।

टेस्ट देने और अपनी प्रोग्रेस सेव करने के लिए साइन इन करें