वह एजेंट जिसे आप नहीं जानते: सिद्धांत, आर्किटेक्चर और इंजीनियरिंग अभ्यास

0. TL;DR

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

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

इसे व्यवस्थित करने में, कई निष्कर्ष मेरी प्रारंभिक धारणाओं से भिन्न निकले: अधिक महंगे मॉडलों द्वारा लाए गए सुधार अक्सर अपेक्षा से छोटे होते हैं; इसके बजाय, हार्नेस और सत्यापन परीक्षणों की गुणवत्ता का सफलता दर पर अधिक प्रभाव पड़ता है। एजेंट व्यवहार को डीबग करते समय, पहले टूल डेफ़िनिशन की जाँच करें, क्योंकि अधिकांश टूल चयन त्रुटियाँ गलत विवरणों से उत्पन्न होती हैं। इसके अलावा, मूल्यांकन प्रणाली के भीतर की समस्याएँ अक्सर एजेंट बग की तुलना में पकड़ में आना अधिक कठिन होती हैं। यदि आप बिना सफलता के एजेंट कोड में बदलाव करते रहते हैं, तो उत्तर इन्हीं क्षेत्रों में हो सकता है।

1. एजेंट लूप का बेसिक ऑपरेशन

एजेंट लूप की मुख्य इम्प्लीमेंटेशन लॉजिक, जब अमूर्त किया जाता है, तो कोड की 20 से कम पंक्तियों में आती है:

1const messages: MessageParam[] = [{ role: "user", content: userInput }];
2
3while (true) {
4  const response = await client.messages.create({
5    model: "claude-opus-4-6",
6    max_tokens: 8096,
7    tools: toolDefinitions,
8    messages,
9  });
10
11  if (response.stop_reason === "tool_use") {
12    const toolResults = await Promise.all(
13      response.content
14        .filter((b) => b.type === "tool_use")
15        .map(async (b) => ({
16          type: "tool_result" as const,
17          tool_use_id: b.id,
18          content: await executeTool(b.name, b.input),
19        }))
20    );
21    messages.push({ role: "assistant", content: response.content });
22    messages.push({ role: "user", content: toolResults });
23  } else {
24    return response.content.find((b) => b.type === "text")?.text ?? "";
25  }
26}

संबंधित कंट्रोल फ्लो इस प्रकार है: धारणा (Perception) -> निर्णय (Decision) -> कार्रवाई (Action) -> प्रतिक्रिया (Feedback) का एक सतत चक्र, जब तक मॉडल सादा टेक्स्ट नहीं लौटाता:

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

नई क्षमताएँ मुख्य रूप से तीन तरीकों से एकीकृत की जाती हैं: टूलसेट और हैंडलर का विस्तार करना, सिस्टम प्रॉम्प्ट संरचनाओं को समायोजित करना, और स्थिति को फ़ाइलों या डेटाबेस में बाहरी बनाना। लूप बॉडी को एक विशाल स्टेट मशीन नहीं बनना चाहिए। मॉडल तर्क को संभालता है, जबकि बाहरी सिस्टम स्थिति और सीमाओं को संभालते हैं। एक बार श्रम का यह विभाजन स्थापित हो जाने पर, मुख्य लूप लॉजिक को शायद ही कभी बार-बार समायोजन की आवश्यकता होती है।

वर्कफ़्लो और एजेंट में क्या अंतर है?

Anthropic एक सीधा अंतर बताता है: एक सिस्टम जहाँ निष्पादन पथ कोड में पूर्व-लिखित होता है, वह वर्कफ़्लो है; एक सिस्टम जहाँ LLM गतिशील रूप से अगला कदम तय करता है, वह एजेंट है। मुख्य अंतर यह है कि नियंत्रण किसके पास है। वास्तव में, एजेंट के रूप में लेबल किए गए कई उत्पाद वर्कफ़्लो के करीब हैं, लेकिन कोई भी स्वाभाविक रूप से बेहतर नहीं है। मायने यह रखता है कि कार्य के लिए सही समाधान खोजा जाए।

एक आरेख में देखने पर यह अधिक सहज लगता है:

पाँच सामान्य नियंत्रण पैटर्न

अधिकांश AI सिस्टम, जब अलग किए जाते हैं, तो इन पाँच पैटर्नों के संयोजन होते हैं। कई परिदृश्यों में पूर्ण एजेंट स्वायत्तता की आवश्यकता नहीं होती; इनमें से कुछ पैटर्नों को मिलाना पर्याप्त होता है। मुख्य बात यह है कि कौन सा डिज़ाइन कार्य के लिए उपयुक्त है।

1. प्रॉम्प्ट चेनिंग: कार्यों को अनुक्रमिक चरणों में विभाजित किया जाता है जहाँ प्रत्येक LLM चरण पिछले आउटपुट को संसाधित करता है। कोड चेकपॉइंट जोड़े जा सकते हैं। रैखिक प्रक्रियाओं के लिए उपयुक्त जैसे जनरेट करने के बाद अनुवाद करना या रूपरेखा के बाद मुख्य भाग लिखना।
2. रूटिंग: इनपुट को वर्गीकृत करता है और इसे एक विशेष प्रक्रिया में निर्देशित करता है। सरल प्रश्न हल्के मॉडलों में जाते हैं, जटिल मजबूत मॉडलों में; तकनीकी सहायता और बिलिंग क्वेरी विभिन्न तर्क का पालन करती हैं।
3. समानांतरीकरण: दो प्रकार: सेक्शनिंग (कार्यों को स्वतंत्र उप-कार्यों में विभाजित करना) और वोटिंग (सर्वसम्मति के लिए एक ही कार्य को कई बार चलाना)। उच्च जोखिम वाले निर्णयों या बहु-दृष्टिकोण आवश्यकताओं के लिए उपयुक्त।
4. ऑर्केस्ट्रेटर-वर्कर्स: एक केंद्रीय LLM गतिशील रूप से कार्यों को विघटित करता है और उन्हें वर्कर LLM को सौंपता है, फिर परिणामों को संश्लेषित करता है। यह nanobot के spawn टूल और learn-claude-code के सब-एजेंट मोड का प्रोटोटाइप है।
5. इवैल्यूएटर-ऑप्टिमाइज़र: एक जनरेटर आउटपुट उत्पन्न करता है, और एक इवैल्यूएटर मानकों को पूरा होने तक लूप में फीडबैक प्रदान करता है। अनुवाद या क्रिएटिव राइटिंग जैसे कार्यों के लिए उपयुक्त जहाँ गुणवत्ता मानकों को कोड में सटीक रूप से परिभाषित करना कठिन होता है।

ये पैटर्न हल करते हैं कि कंट्रोल फ्लो कैसे बनाया जाए। अब एक अधिक इंजीनियरिंग-केंद्रित प्रश्न देखते हैं: एक सिस्टम स्थिर रूप से क्यों चलता है?

2. हार्नेस मॉडल से अधिक महत्वपूर्ण क्यों है

हार्नेस एक एजेंट के चारों ओर बनाए गए परीक्षण, सत्यापन और बाधा बुनियादी ढाँचे को संदर्भित करता है। एक हार्नेस में कम से कम चार भाग शामिल होते हैं: स्वीकृति आधार रेखाएँ, निष्पादन सीमाएँ, प्रतिक्रिया संकेत और फ़ॉलबैक विधियाँ।

जबकि मॉडल महत्वपूर्ण है, ये परिधीय इंजीनियरिंग स्थितियाँ अक्सर यह निर्धारित करती हैं कि कोई सिस्टम स्थिर रूप से चलता है या नहीं। यह निर्णय कोडिंग जैसे अत्यधिक सत्यापन योग्य कार्यों के लिए सबसे सत्य है, लेकिन ओपन रिसर्च या मल्टी-राउंड नेगोशिएशन जैसे कमजोर सत्यापन कार्यों में, मॉडल की ऊपरी सीमा अधिक महत्वपूर्ण बनी रहती है।

OpenAI का एजेंट-प्रथम विकास अभ्यास

तीन इंजीनियरों ने लगभग 1,500 PR के साथ पाँच महीनों में दस लाख लाइनों का कोड लिखा—पारंपरिक विकास की गति से 10 गुना। यह गति केवल मॉडल की ताकत के बारे में नहीं थी; यह सही इंजीनियरिंग निर्णयों के बारे में थी:

1. एजेंट जो नहीं देख सकता, वह अस्तित्व में नहीं है: ज्ञान को कोडबेस में ही मौजूद होना चाहिए। बाहरी दस्तावेज़ चल रहे एजेंट के लिए अदृश्य होते हैं। AGENTS.md को एक इंडेक्स के रूप में ~100 लाइनों पर रखा जाता है, विवरणों को ऑन-डिमांड संदर्भ के लिए docs निर्देशिकाओं में विभाजित किया जाता है।
2. कोड बाधाएँ, उनका दस्तावेज़ीकरण न करें: दस्तावेज़ों में मानदंड आसानी से अनदेखा किए जाते हैं। Linters, टाइप सिस्टम या CI नियमों में एन्कोड की गई बाधाएँ निष्पादन योग्य होती हैं। आर्किटेक्चरल लेयरिंग को मैन्युअल समीक्षा के बजाय कस्टम Linters द्वारा यांत्रिक रूप से लागू किया जाता है।
3. एंड-टू-एंड स्वायत्त कार्य पूर्णता: स्थिति सत्यापित करने और बग को पुन: उत्पन्न करने से लेकर फिक्स लागू करने और ऐप सत्यापन चलाने, PR खोलने, समीक्षा संभालने और मर्ज करने तक—पूरी श्रृंखला में किसी मानवीय हस्तक्षेप की आवश्यकता नहीं होती है। एजेंट सक्रिय रूप से लॉग, मेट्रिक्स और ट्रेस की जाँच करते हैं।
4. मर्ज घर्षण को कम करें: प्रगति को अवरुद्ध करने के बजाय रीट्राई के साथ आंतरायिक परीक्षण विफलताओं को संभालें। उच्च-थ्रूपुट वातावरण में, मैन्युअल समीक्षा की प्रतीक्षा करने की लागत अक्सर छोटी त्रुटियों को ठीक करने से अधिक होती है। कोडिंग अनुशासन गायब नहीं हुआ है; यह मैन्युअल समीक्षा से मशीन-निष्पादित बाधाओं में स्थानांतरित हो गया है।

ऐप लॉग, मेट्रिक्स और ट्रेस को Vector के माध्यम से Victoria स्टोरेज लेयर में वितरित करता है, जो LogQL, PromQL और TraceQL इंटरफेस के अनुरूप है। Codex इन इंटरफेस के माध्यम से क्वेरी करता है, सहसंबंधित करता है और तर्क करता है। परिवर्तनों के बाद, यह ऐप को पुनरारंभ करता है, वर्कलोड को फिर से चलाता है, और परिणामों को Codex को वापस फीड करता है। UI Journeys भी इनपुट हैं। यह ऑब्ज़र्वेबिलिटी स्टैक प्रति कार्य बनाया जाता है और पूरा होने पर नष्ट कर दिया जाता है। एजेंट त्रुटियों के बारे में बताए जाने की प्रतीक्षा नहीं करता; वह फिक्स सत्यापित करने के लिए सिस्टम स्थिति क्वेरी करता है।

हार्नेस के लिए मुख्य निष्कर्ष क्या है?

आरेख कार्य स्पष्टता और सत्यापन स्वचालन का उपयोग करके कार्यों को चार अवस्थाओं में विभाजित करता है। ऊपर-दाएँ (स्पष्ट लक्ष्य, स्वचालित सत्यापन) एजेंटों के लिए आदर्श क्षेत्र है। ऊपर-बाएँ (स्पष्ट कार्य लेकिन मैन्युअल समीक्षा) मानव समीक्षा गति द्वारा सीमित है। नीचे-दाएँ (स्वचालित प्रतिक्रिया लेकिन अस्पष्ट लक्ष्य) गलत दिशा में कुशल गति की ओर ले जाता है। नीचे-बाएँ (दोनों का अभाव) एजेंटों को बेकार बना देता है।

हार्नेस का काम कार्यों को ऊपर-दाएँ में धकेलना है, यह सुनिश्चित करना कि सही और गलत का निर्णय मानव आँखों के बजाय मशीन-निष्पादित मानकों द्वारा किया जाए।

3. कॉन्टेक्स्ट इंजीनियरिंग स्थिरता क्यों निर्धारित करती है

ट्रांसफॉर्मर अटेंशन जटिलता O(n²) है। संदर्भ जितना लंबा होगा, प्रमुख संकेतों के शोर में घुलने की संभावना उतनी ही अधिक होगी। एक सामान्य विफलता मोड "कॉन्टेक्स्ट रॉट" है, जहाँ अप्रासंगिक सामग्री संदर्भ पर हावी हो जाती है, जिससे एजेंट निर्णय गुणवत्ता में गिरावट आती है। मॉडल अक्षमता के रूप में दिखाई देने वाली कई समस्याएँ वास्तव में खराब संदर्भ संगठन के कारण होती हैं।

संदर्भ को स्तरित क्यों करें?

समस्या आमतौर पर यह नहीं है कि विंडो पर्याप्त लंबी नहीं है, बल्कि यह है कि सूचना घनत्व गलत है। हर बार शायद ही कभी उपयोग की जाने वाली वस्तुओं को लोड करना या स्थिर नियमों को गतिशील अवस्थाओं के साथ मिलाना मॉडल के लिए उपयोगी चीज़ों को नोटिस करना कठिन बना देता है।

समाधान आवृत्ति और स्थिरता के अनुसार जानकारी को स्तरित करना है:

• स्थायी परत: पहचान, परियोजना सम्मेलन, पूर्ण निषेध। ऐसी सामग्री जो प्रत्येक सत्र के लिए मान्य होनी चाहिए। इसे छोटा, कठोर और निष्पादन योग्य रखें।
• ऑन-डिमांड लोडिंग: कौशल और डोमेन ज्ञान। विवरणों को स्थायी रखें, लेकिन पूर्ण सामग्री को केवल ट्रिगर होने पर ही इंजेक्ट करें।
• रनटाइम इंजेक्शन: वर्तमान समय, चैनल आईडी, उपयोगकर्ता प्राथमिकताएँ जैसी गतिशील जानकारी। आवश्यकतानुसार प्रति राउंड इंजेक्ट की जाती है।
• मेमोरी परत: क्रॉस-सेशन अनुभव MEMORY.md में लिखा जाता है। सीधे सिस्टम प्रॉम्प्ट में नहीं; केवल आवश्यकता होने पर पढ़ा जाता है।
• सिस्टम परत: नियतात्मक तर्क के लिए हुक या कोड नियम। संदर्भ से पूरी तरह बाहर रहता है।

नियतात्मक तर्क को संदर्भ में न रखें। जो कुछ भी हुक, कोड नियम या टूल बाधाओं के माध्यम से व्यक्त किया जा सकता है, उसे बाहरी सिस्टम द्वारा संभाला जाना चाहिए।

तीन सामान्य संपीड़न रणनीतियाँ

1. स्लाइडिंग विंडो: पुराने संदेशों को हटा देता है। कम लागत, लेकिन प्रारंभिक संदर्भ खो देता है। छोटी चैट के लिए अच्छा।
2. LLM सारांश: मॉडल एक सारांश उत्पन्न करता है। मध्यम लागत, विवरण खो देता है लेकिन निर्णय रखता है। लंबे कार्यों के लिए अच्छा।
3. टूल परिणाम प्रतिस्थापन: कच्चे आउटपुट को प्लेसहोल्डर से बदल देता है। कम लागत, टूल-भारी कार्यों के लिए अच्छा।

स्लाइडिंग विंडो सबसे आसान हैं लेकिन प्रारंभिक पृष्ठभूमि खो देती हैं। उन्नत LLM सारांश "शाखा सारांश" का उपयोग करते हैं, जो स्पष्ट रूप से आर्किटेक्चरल निर्णय, अधूरे कार्य और प्रमुख बाधाओं को संरक्षित करते हैं। टूल प्रतिस्थापन में, micro_compact हर राउंड पुराने टूल आउटपुट को बदल देता है, जबकि auto_compact तब ट्रिगर होता है जब संदर्भ एक सीमा से अधिक हो जाता है।

अनावश्यक ओवरहेड को कम करने के लिए प्रॉम्प्ट कैशिंग

LLM इन्फ्रेंस प्रत्येक टोकन के लिए Key-Value जोड़े की गणना करता है। यदि कोई उपसर्ग पिछले अनुरोध से बिल्कुल मेल खाता है, तो इसे कैश से पढ़ा जाता है। कैशिंग के लिए सटीक उपसर्ग मिलान की आवश्यकता होती है। कैश-अनुकूल डिज़ाइन स्थिरता पर केंद्रित है: सिस्टम प्रॉम्प्ट, टूल डेफ़िनिशन और लंबे दस्तावेज़ स्थिर होते हैं और कैशिंग के लिए उपयुक्त होते हैं। गतिशील जानकारी (समय, इनपुट, टूल परिणाम) को अंत में रखा जाना चाहिए।

यह संदर्भ स्तरीकरण से संबंधित है। स्थायी परत जितनी अधिक स्थिर होगी, कैश हिट दर उतनी ही अधिक और सीमांत लागत उतनी ही कम होगी। "छोटा और स्थिर" केवल टोकन बचाने के लिए नहीं है; यह कैश की रक्षा करता है। विलंबित कौशल लोडिंग भी स्थिर उपसर्ग के बाद सामग्री जोड़कर मदद करती है। एक प्रति-सहज ज्ञान बिंदु: एक स्थिर बड़ा सिस्टम प्रॉम्प्ट बार-बार बदलने वाले छोटे सिस्टम प्रॉम्प्ट से सस्ता हो सकता है क्योंकि बाद के रीड पर 90% की छूट प्रारंभिक राइट लागत से अधिक होती है।

ऑन-डिमांड स्किल क्यों लोड करें?

कौशल एक प्रभावी पैटर्न है: सिस्टम प्रॉम्प्ट में केवल इंडेक्स रखें, आवश्यकतानुसार पूर्ण ज्ञान लोड करें।

1const systemPrompt = `
2उपलब्ध कौशल:
3- deploy: पूर्ण प्रोडक्शन डिप्लॉयमेंट प्रक्रिया
4- code-review: कोड समीक्षा चेकलिस्ट
5- git-workflow: शाखा रणनीति और PR मानदंड
6`;
7
8async function executeLoadSkill(name: string): Promise<string> {
9  return fs.readFile(`./skills/${name}.md`, "utf-8");
10}

कौशल विवरण टोकन ब्लोट से बचने के लिए छोटे होने चाहिए और रूटिंग शर्तों के रूप में कार्य करने चाहिए। बताएं कि इसका उपयोग कब करना है, कब नहीं करना है, और आउटपुट क्या है। "उपयोग करें जब / उपयोग न करें जब" का उपयोग नकारात्मक उदाहरणों के साथ करें। कई रूटिंग विफलताएँ मॉडल क्षमता के बजाय अस्पष्ट सीमाओं के कारण होती हैं। सिस्टम प्रॉम्प्ट को नियम स्पष्ट करने चाहिए: प्रत्येक उत्तर से पहले available_skills को स्कैन करें, मिलान होने पर विशिष्ट SKILL.md लोड करें, और एक बार में केवल एक लोड करें।

डेटा स्पष्ट है: नकारात्मक उदाहरणों के बिना, सटीकता 73% से गिरकर 53% हो जाती है; उन्हें जोड़ने से यह बढ़कर 85% हो जाती है और प्रतिक्रिया समय 18.1% कम हो जाता है। नकारात्मक उदाहरण महत्वपूर्ण हैं।

कौशल विवरणकों में दो जाल हैं। पहला, शब्द गणना: प्रत्येक कौशल के लिए लंबे विवरण जुड़ते जाते हैं। दूसरा, सटीकता: "बैकएंड में मदद करें" बहुत अस्पष्ट है। प्रभावी विवरणक रूटिंग शर्तें हैं, सुविधा परिचय नहीं। "मेरा उपयोग कब करें" "मैं क्या कर सकता हूँ" से अधिक महत्वपूर्ण है।

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

संपीड़न सबसे आसानी से क्या खोता है?

सबसे आम समस्या यह नहीं है कि सारांश बहुत लंबा है, बल्कि यह है कि प्रतिधारण प्राथमिकता गलत है। LLM अक्सर उस जानकारी को हटा देते हैं जो पुनः प्राप्त करने योग्य लगती है। टूल आउटपुट पहले जाते हैं, लेकिन संबंधित आर्किटेक्चरल निर्णय और विफलता पथ भी अक्सर गायब हो जाते हैं। CLAUDE.md में प्रतिधारण प्राथमिकताओं को स्पष्ट रूप से परिभाषित करें:

1### कॉम्पैक्ट निर्देश: प्रमुख जानकारी कैसे बनाए रखें
2प्राथमिकता:
31. आर्किटेक्चरल निर्णय (सारांश न करें)
42. संशोधित फ़ाइलें और प्रमुख परिवर्तन
53. सत्यापन स्थिति (पास/फेल)
64. अनसुलझे TODO और रोलबैक नोट्स
75. टूल आउटपुट (हटा सकते हैं, केवल पास/फेल निष्कर्ष रखें)

एक और जाल: पहचानकर्ताओं को न बदलें। UUID, हैश, IP और फ़ाइल नामों को बिल्कुल संरक्षित किया जाना चाहिए। कमिट हैश में एक गलत वर्ण बाद के टूल कॉल को तोड़ देता है।

फ़ाइल सिस्टम महान संदर्भ इंटरफ़ेस क्यों हैं

Cursor इसे "डायनेमिक कॉन्टेक्स्ट डिस्कवरी" कहता है: डिफ़ॉल्ट रूप से कम दें, आवश्यकता होने पर पढ़ें। फ़ाइल सिस्टम प्राकृतिक इंटरफ़ेस हैं। टूल कॉल अक्सर विशाल JSON लौटाते हैं; इसे संदर्भ में भरने के बजाय, इसे एक फ़ाइल में लिखें। एजेंट आवश्यकतानुसार पढ़ने के लिए grep या rg का उपयोग कर सकता है। यह संदर्भ को साफ रखता है और डेवलपर-पठनीय है।

Cursor ने इसे MCP टूल से सत्यापित किया: वे टूल विवरणों को फ़ोल्डरों में सिंक करते हैं। एजेंट डिफ़ॉल्ट रूप से केवल टूल नाम देखते हैं और आवश्यकतानुसार परिभाषाएँ क्वेरी करते हैं। A/B परीक्षणों में, इसने कुल टोकन खपत को 46.9% कम कर दिया।

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

4. टूल डिज़ाइन निर्धारित करता है कि एजेंट क्या कर सकता है

संदर्भ यह निर्धारित करता है कि मॉडल क्या देखता है; उपकरण यह निर्धारित करते हैं कि वह क्या कर सकता है। गुणवत्ता मात्रा से बेहतर है। सिर्फ 5 MCP सर्वरों की परिभाषाओं में ~55,000 टोकन खर्च हो सकते हैं—चैट शुरू होने से पहले ही 200K संदर्भ का लगभग 30%। बहुत सारे उपकरण मॉडल का ध्यान कमजोर कर देते हैं।

अधिकांश टूल समस्याएँ बहुत कम होने के बारे में नहीं हैं, बल्कि गलत को चुनने, समझ से बाहर विवरण, या बेकार डेटा लौटाने के बारे में हैं।

टूल डिज़ाइन कैसे विकसित होता है

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

पहली पीढ़ी: API रैपिंग: प्रत्येक एंडपॉइंट एक उपकरण है। बहुत दानेदार; एजेंटों को एक लक्ष्य के लिए कई उपकरणों का समन्वय करना होता है।

दूसरी पीढ़ी: ACI (एजेंट-कंप्यूटर इंटरफ़ेस): उपकरण एजेंट लक्ष्यों के अनुरूप होते हैं, निम्न-स्तरीय API से नहीं। create_file और set_permissions प्रदान करने के बजाय, create_script(path, content, executable) प्रदान करें।

तीसरी पीढ़ी: उन्नत टूल उपयोग: खोज और कॉलिंग का अनुकूलन:

• टूल खोज: सभी परिभाषाओं को एक साथ न भरें। एजेंट search_tools के माध्यम से परिभाषाएँ ढूँढते हैं। संदर्भ प्रतिधारण 95% तक पहुँच जाता है।
• प्रोग्रामेटिक टूल कॉलिंग: मॉडल को कई कॉल ऑर्केस्ट्रेट करने के लिए कोड का उपयोग करने दें। मध्यवर्ती परिणाम LLM संदर्भ के बजाय निष्पादन वातावरण में रहते हैं। टोकन 150,000 से घटकर 2,000 हो सकते हैं।
• टूल उपयोग उदाहरण: प्रत्येक उपकरण को 1-5 वास्तविक उदाहरण मिलते हैं। JSON Schema प्रकारों का वर्णन करता है, लेकिन उदाहरण उपयोग दिखाते हैं। सटीकता 72% से बढ़कर 90% हो सकती है।

ACI टूल डिज़ाइन सिद्धांत

टूल डिज़ाइन एजेंटों को सीधे प्रभावित करता है। यह सिर्फ "क्या इसे कॉल किया जा सकता है" नहीं है, बल्कि "क्या यह गलत कॉल होने पर स्वयं को सुधार सकता है?"

खराब डिज़ाइन में अस्पष्ट पैरामीटर और गैर-सुधार योग्य त्रुटियाँ होती हैं। अच्छे डिज़ाइन परिभाषा और कार्यान्वयन को बांधने के लिए betaZodTool का उपयोग करते हैं, प्रारूप बाधाओं और संरचित त्रुटि सुझावों के लिए Zod का उपयोग करते हैं:

1const updateTool = betaZodTool({
2  name: "update_yuque_post",
3  description: "Yuque पोस्ट सामग्री अपडेट करता है; नई पोस्ट बनाने के लिए नहीं",
4  inputSchema: z.object({
5    post_id: z.string().describe("Yuque पोस्ट ID, संख्यात्मक स्ट्रिंग जैसे '12345678'"),
6    title: z.string().optional().describe("पोस्ट शीर्षक, अपरिवर्तित होने पर छोड़ दें"),
7    content_markdown: z.string().describe("Markdown बॉडी"),
8  }),
9  run: async (input) => {
10    const post = await getPost(input.post_id);
11    if (!post) throw new ToolError("पोस्ट ID मौजूद नहीं है", {
12      error_code: "POST_NOT_FOUND",
13      suggestion: "एक वैध post_id प्राप्त करने के लिए पहले list_yuque_posts कॉल करें",
14    });
15    return await updatePost(input.post_id, input.title, input.content_markdown);
16  },
17});

खराब डिज़ाइन केवल यह बताता है कि यह क्या करता है, न कि इसका उपयोग कब करना है। अच्छे ACI डिज़ाइन में स्पष्ट सीमाएँ और संरचित त्रुटियाँ होती हैं, जो एजेंटों को सही ढंग से चुनने और विफलताओं को जल्दी ठीक करने में मदद करती हैं। पहले उपकरणों को डीबग करें; अधिकांश त्रुटियाँ मॉडल क्षमता के बजाय विवरणों में होती हैं।

टूल संदेशों को अलग क्यों करें?

फ्रेमवर्क आंतरिक ईवेंट (संपीड़न, सूचनाएँ) उत्पन्न करते हैं। ये सत्र इतिहास में होने चाहिए लेकिन LLM को नहीं भेजे जाने चाहिए, क्योंकि ये टोकन बर्बाद करते हैं और मॉडल को भ्रमित करते हैं। समाधान दो संदेश प्रकार हैं: ऐप लेयर के लिए AgentMessage (कस्टम फ़ील्ड के साथ) और LLM के लिए मानक Message (user, assistant, tool_result)।

5. मेमोरी सिस्टम डिज़ाइन करना

एजेंटों में देशी अस्थायी निरंतरता का अभाव है। एक सत्र के बाद संदर्भ साफ़ हो जाता है। क्रॉस-सेशन स्थिरता प्राप्त करने के लिए, एक मेमोरी लेयर को बुनियादी ढाँचे के रूप में डिज़ाइन किया जाना चाहिए, न कि एक बाद के विचार के रूप में।

चार प्रकार की मेमोरी कहाँ रहती है?

उनके द्वारा हल की जाने वाली समस्या के अनुसार वर्गीकृत:

• कॉन्टेक्स्ट विंडो (वर्किंग मेमोरी): वर्तमान कार्य के लिए न्यूनतम जानकारी। सीमित टोकन; प्रबंधित किया जाना चाहिए।
• कौशल (प्रक्रियात्मक मेमोरी): चीजें कैसे करें (वर्कफ़्लो, मानदंड)। ऑन-डिमांड लोड किया जाता है।
• JSONL सत्र इतिहास (एपिसोडिक मेमोरी): क्या हुआ। डिस्क पर संग्रहीत; खोजने योग्य।
• MEMORY.md (सिमैंटिक मेमोरी): एजेंट द्वारा लिखे गए स्थिर तथ्य। सिस्टम प्रॉम्प्ट में इंजेक्ट किए जाते हैं।

MEMORY.md और कौशल कैसे सहयोग करते हैं

मुख्य बात सामग्री की मात्रा को नियंत्रित करते हुए महत्वपूर्ण तथ्यों को रखना है।

ChatGPT की 4-परत मेमोरी: सरल संरचना। सत्र मेटाडेटा (संग्रहीत नहीं), उपयोगकर्ता मेमोरी (~33 तथ्य, संग्रहीत/इंजेक्टेड), वार्तालाप सारांश (~15 हालिया सारांश, संग्रहीत), वर्तमान सत्र (स्लाइडिंग विंडो)।

OpenClaw हाइब्रिड रिट्रीवल: दैनिक लॉग (memory/YYYY-MM-DD.md), क्यूरेटेड तथ्यों के लिए MEMORY.md, और हाइब्रिड रिट्रीवल (70% वेक्टर समानता + 30% कीवर्ड) का उपयोग करके memory_search। अधिकांश एजेंटों के लिए, संरचित Markdown + कीवर्ड खोज डीबगेबिलिटी और लागत के लिए पर्याप्त है।

मेमोरी समेकन को ट्रिगर और रोलबैक करना

जब tokenUsage / maxTokens >= 0.5 हो, तो समेकन ट्रिगर करें। संदेशों का सारांश बनाएं, MEMORY.md में जोड़ें, और इंडेक्स अपडेट करें। यदि यह विफल होता है, तो कच्चे संदेशों को एक संग्रह में लिखें। प्रक्रिया प्रतिवर्ती होनी चाहिए; पॉइंटर्स को स्थानांतरित करें, कच्चे डेटा को हटाएं नहीं।

6. धीरे-धीरे एजेंट स्वायत्तता बढ़ाना

स्वायत्तता के लिए तीन बुनियादी ढाँचे की आवश्यकता होती है: क्रॉस-सेशन पुनरारंभ, इन-सेशन प्रगति बाधाएँ, और धीमे कार्यों के लिए बैकग्राउंड I/O।

लंबे कार्यों को सत्रों में कैसे जारी रखें

लंबे कार्य तब विफल होते हैं जब पूरा होने से पहले सत्र समाप्त हो जाते हैं। एक स्थिर दृष्टिकोण एक इनिशियलाइज़र एजेंट और एक कोडिंग एजेंट का उपयोग करता है। इनिशियलाइज़र एक बार चलकर feature-list.json, init.sh और claude-progress.txt बनाता है। कोडिंग एजेंट तब कई सत्रों में चलता है, इन फ़ाइलों से फिर से शुरू होता है, एक सुविधा लागू करता है, परीक्षण चलाता है, और प्रगति फ़ाइल अपडेट करता है। यह कार्य को एक बाहरी स्थिति बनाता है।

प्रगति को फ़ाइलों में रखें, संदर्भ में नहीं। संरचना के लिए JSON का उपयोग करें। कार्य तभी पूरा होता है जब feature-list.json में सभी सुविधाओं के लिए passes: true हो।

कार्य स्थिति को स्पष्ट रूप से क्यों लिखें?

बाहरी एंकर के बिना, एजेंट भटक जाते हैं या समय से पहले समाप्त हो जाते हैं। स्थिति को एक बाहरी नियंत्रण वस्तु के रूप में रिकॉर्ड करें:

1{
2  "tasks": [
3    {"id": "1", "desc": "कॉन्फ़िग पढ़ें", "status": "completed"},
4    {"id": "2", "desc": "स्कीमा संशोधित करें", "status": "in_progress"}
5  ]
6}

बाधा: एक समय में केवल एक in_progress। प्रत्येक चरण के बाद स्थिति अपडेट करें।

बैकग्राउंड I/O को एकीकृत करना

धीमा I/O (फ़ाइल ऑप, नेटवर्क) को मुख्य लूप को ब्लॉक नहीं करना चाहिए। धीमी उपप्रक्रियाओं को बैकग्राउंड थ्रेड में रखें और अगले LLM कॉल से पहले एक सूचना कतार के माध्यम से परिणाम इंजेक्ट करें। यह एक जटिल async रनटाइम की तुलना में अधिक रखरखाव योग्य है।

7. मल्टी-एजेंट सिस्टम का आयोजन

मल्टी-एजेंट सिस्टम की इंजीनियरिंग अलगाव और सहयोग के बारे में है।

निर्देशक मोड: सिंक्रोनस। मानव एक एजेंट के साथ निकटता से बातचीत करता है। सत्र समाप्त होने पर संदर्भ खो जाता है।

समन्वयक मोड: एसिंक्रोनस प्रतिनिधिमंडल। मानव लक्ष्य निर्धारित करता है, एजेंट समानांतर में काम करते हैं, मानव आउटपुट की समीक्षा करता है। आउटपुट स्थायी कलाकृतियाँ (PR, शाखाएँ) बन जाते हैं।

एक ऑर्केस्ट्रेटर सब-एजेंट का प्रबंधन करता है जो समानांतर में काम करते हैं, JSONL इनबॉक्स प्रोटोकॉल के माध्यम से संचार करते हैं और अलगाव के लिए Worktrees का उपयोग करते हैं।

सब-एजेंट किसके लिए अच्छे हैं?

खोज और परीक्षण-और-त्रुटि को मुख्य एजेंट के संदर्भ को प्रदूषित नहीं करना चाहिए। मुख्य एजेंट को केवल निष्कर्ष की आवश्यकता है।

1const result = await runAgentLoop(task, { messages: [] });
2return summarize(result); // मुख्य संदर्भ केवल इस लाइन को देखता है

सहयोग को प्रोटोकॉल के रूप में क्यों लिखें?

प्राकृतिक भाषा सहयोग विफल हो जाता है क्योंकि एजेंट वादे भूल जाते हैं। एक संरचित प्रोटोकॉल का उपयोग करें:

1{ request_id, from_agent, to_agent, content, status: 'pending', timestamp }

क्रैश रिकवरी के लिए एक append-only JSONL इनबॉक्स का उपयोग करें। पहले अलगाव, फिर सहयोग।

मल्टी-एजेंट सिस्टम में मतिभ्रम बढ़ता है

एजेंटों के बीच त्रुटियाँ कैस्केड होती हैं। क्रॉस-वैलिडेशन एक स्वतंत्र एजेंट या बाहरी प्रतिक्रिया (परीक्षण, कंपाइलर) द्वारा निष्कर्ष का न्याय करके इस श्रृंखला को तोड़ता है।

8. एजेंटों का मूल्यांकन कैसे करें

मूल्यांकन के लिए परीक्षण मामलों, स्कोरिंग मानकों और स्वचालित सत्यापन की आवश्यकता होती है।

पारंपरिक सिंगल-टर्न eval (प्रॉम्प्ट -> प्रतिक्रिया) अपर्याप्त है। एजेंट eval के लिए उपकरणों और वातावरण की आवश्यकता होती है। स्कोरिंग इस बात पर आधारित है कि वातावरण में क्या हुआ, न कि केवल एजेंट ने क्या कहा।

मुख्य अवधारणाएँ: कार्य, परीक्षण, ग्रेडर। प्रतिलेख (निष्पादन लॉग) बनाम परिणाम (अंतिम स्थिति)। आपको दोनों की आवश्यकता है। एक एजेंट कह सकता है "टिकट बुक हो गया" (प्रतिलेख) लेकिन डेटाबेस रिकॉर्ड बनाने में विफल हो सकता है (परिणाम)।

मूल्यांकन स्थिति और मीट्रिक्स

कई टीमें अभी भी मैन्युअल समीक्षा या LLM जजों पर निर्भर करती हैं। सामान्य मीट्रिक्स: Pass@k (क्या यह सैद्धांतिक रूप से कर सकता है?) और Pass^k (क्या यह प्रोडक्शन के लिए स्थिर है?)। इन्हें मिलाएं नहीं।

ग्रेडर्स के तीन प्रकार

1. कोड ग्रेडर्स: स्ट्रिंग मैचिंग, यूनिट टेस्ट। सबसे अधिक निश्चितता।
2. मॉडल ग्रेडर्स: मानदंडों के आधार पर LLM जज। सिमैंटिक गुणवत्ता के लिए अच्छा।
3. ह्यूमन ग्रेडर्स: विशेषज्ञ समीक्षा। धीमा लेकिन बेसलाइन स्थापित करता है।

शून्य से Eval सिस्टम बनाना

20-50 वास्तविक विफलता मामलों से शुरू करें। सुनिश्चित करें कि पर्यावरण अलग-थलग हो ताकि टेस्ट एक-दूसरे को प्रभावित न करें। सकारात्मक और नकारात्मक दोनों मामलों को शामिल करें। यदि दो विशेषज्ञ किसी मामले पर असहमत हैं, तो मानदंड अभी स्पष्ट नहीं हैं।

एजेंट को ठीक करने से पहले Eval को ठीक करें

यदि स्कोर गिरते हैं, तो पहले eval सिस्टम की जांच करें। पर्यावरण संबंधी समस्याएं (मेमोरी सीमाएं, ग्रेडर्स में बग) मॉडल डिग्रेडेशन की तरह दिखती हैं।

9. निष्पादन प्रक्रिया का ट्रेसिंग

ट्रेस के बिना, विफलताओं को दोहराया नहीं जा सकता। APM मीट्रिक्स (लेटेंसी, एरर रेट) पर्याप्त नहीं हैं; आपको रीज़निंग चेन की आवश्यकता है।

ट्रेस में क्या रिकॉर्ड करें?

पूरा प्रॉम्प्ट, मल्टी-राउंड मैसेज, टूल कॉल्स/आर्ग्स/रिटर्न्स, थिंकिंग चेन, अंतिम आउटपुट, टोकन्स, और लेटेंसी।

दो-परत अवलोकनीयता

1. मैन्युअल सैंपलिंग: विफलता पैटर्न खोजने के लिए त्रुटियों या नकारात्मक फीडबैक का नियम-आधारित सैंपलिंग।
2. LLM ऑटो-ईवल: मैन्युअल लेयर को कैलिब्रेशन बेसलाइन के रूप में उपयोग करते हुए ट्रेस का पूर्ण कवरेज।

इवेंट स्ट्रीम्स आधार के रूप में

tool_start, tool_end, और turn_end पर इवेंट उत्सर्जित करें। डाउनस्ट्रीम सिस्टम (लॉग्स, UI, eval) कोर लूप कोड को बदले बिना इन इवेंट्स का उपभोग करते हैं।

10. OpenClaw के साथ एजेंट्स को लैंड करना

OpenClaw पांच डिकपल्ड लेयर्स का उपयोग करता है: गेटवे, चैनल एडेप्टर, Pi एजेंट (कोर लूप), टूलसेट (ACI डिज़ाइन), और कॉन्टेक्स्ट/मेमोरी।

मैसेज बस डिकपलिंग

एक मैसेज बस चैनल्स को एजेंट से अलग करता है। चैनल केवल I/O संभालते हैं; एजेंट केवल प्रोसेसिंग संभालता है।

सिस्टम प्रॉम्प्ट्स लेयर्स में

SOUL.md पहचान और पूर्णता मानकों को परिभाषित करता है। प्रॉम्प्ट्स लेयर्ड होते हैं: रनटाइम जानकारी -> पहचान -> मेमोरी -> कौशल -> डायनामिक इंजेक्शन।

पहले सुरक्षा सीमाएं

सुविधाएं जोड़ने से पहले, स्थापित करें: यूज़र व्हाइटलिस्ट्स, वर्कस्पेस आइसोलेशन (पथ जांच), और ऑडिट लॉग्स।

प्रॉम्प्ट इंजेक्शन सुरक्षा: बाहरी सामग्री को अविश्वसनीय मानें। स्रोत-सिंक पृथक्करण का उपयोग करें। एजेंट्स को वे उपकरण न दें जिनकी उन्हें आवश्यकता नहीं है। संवेदनशील कार्यों के लिए स्पष्ट मानव पुष्टि की आवश्यकता हो।

प्रोवाइडर फॉलबैक: यदि कोई विफल होता है तो स्वचालित रूप से प्रोवाइडर बदलें (Anthropic -> OpenAI)।

11. सामान्य एंटी-पैटर्न

1. सिस्टम प्रॉम्प्ट को नॉलेज बेस के रूप में उपयोग करना (बहुत लंबा)।
2. टूल स्प्रॉल (एजेंट गलत टूल चुनता है)।
3. सत्यापन लूप्स का अभाव।
4. सीमाओं के बिना मल्टी-एजेंट सिस्टम।
5. मेमोरी समेकन नहीं (20 राउंड के बाद गुणवत्ता गिरती है)।
6. कोई मूल्यांकन प्रणाली नहीं।
7. समय से पहले मल्टी-एजेंट जटिलता।
8. यांत्रिक बाधाओं के बजाय अपेक्षाओं पर निर्भर रहना।

12. निष्कर्ष

1. एजेंट कोर एक स्थिर लूप है; नई सुविधाओं को बाहरी किया जाना चाहिए।
2. हार्नेस मॉडल से अधिक अभिसरण निर्धारित करता है।
3. कॉन्टेक्स्ट इंजीनियरिंग 'कॉन्टेक्स्ट रॉट' को रोकती है।
4. ACI टूल डिज़ाइन लक्ष्यों और त्रुटि सुधार पर केंद्रित है।
5. मेमोरी लेयर्ड है (वर्किंग, प्रोसीजरल, एपिसोडिक, सिमैंटिक)।
6. लंबे कार्य बाहरी स्थिति और फ़ाइलों पर निर्भर करते हैं।
7. मल्टी-एजेंट सिस्टम को प्रोटोकॉल और आइसोलेशन की आवश्यकता है।
8. क्षमता के लिए Eval Pass@k, गुणवत्ता के लिए Pass^k।
9. ट्रेसिंग डिबगिंग के लिए पूर्वापेक्षा है।
10. स्थिर एजेंट डिकपलिंग और सुरक्षा सीमाओं जैसे इंजीनियरिंग विवरणों पर निर्भर करते हैं।