एजेंट हार्नेस इंजीनियरिंग

एक कोडिंग एजेंट, मॉडल और उसके चारों ओर बनी हर चीज़ का संयोजन है। हार्नेस इंजीनियरिंग उस स्कैफोल्डिंग को एक जीवित कलाकृति मानती है, और हर बार जब एजेंट कोई गलती करता है, उसे कसती है।

सीधे शब्दों में: जब भी कोई एजेंट असफल होता है, आप एक स्थायी समाधान इंजीनियर करते हैं ताकि वह फिर कभी वही सटीक गलती न दोहराए।

पिछले दो वर्षों से, उद्योग मॉडलों पर बहस कर रहा है: कौन सा सबसे बुद्धिमान है, कौन सा सबसे साफ React लिखता है, या कौन सा सबसे कम भ्रम पैदा करता है। हालांकि यह चर्चा महत्वपूर्ण है, यह सिस्टम के दूसरे आधे हिस्से को अनदेखा करती है।

मॉडल एक चल रहे एजेंट में केवल एक इनपुट है। बाकी हार्नेस है: प्रॉम्प्ट, टूल्स, कॉन्टेक्स्ट पॉलिसियाँ, हुक्स, सैंडबॉक्स, सबएजेंट, फीडबैक लूप्स, और रिकवरी पथ जो मॉडल के चारों ओर लपेटे जाते हैं ताकि वह वास्तव में कार्य पूरा कर सके।

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

उस अनुशासन का अब एक नाम है। @Vtrivedy10 ने हार्नेस इंजीनियरिंग शब्द गढ़ा, जिसमें स्पष्ट रूप से बताया गया कि हार्नेस वास्तव में क्या है और प्रत्येक भाग क्यों मौजूद है। उद्योग के अन्य आवाज़ें जैसे @dexhorthy उभरते पैटर्न को ट्रैक कर रहे हैं, HumanLayer एजेंट विफलताओं को कॉन्फ़िगरेशन "स्किल इश्यू" के रूप में फ्रेम कर रहा है, Anthropic की इंजीनियरिंग टीम लंबे समय तक चलने वाले ऐप डिज़ाइन पर गाइड प्रकाशित कर रही है, और Birgitta Böckeler उपयोगकर्ता-पक्ष के अनुभव की खोज कर रही हैं - ये सभी मोटे तौर पर एक ही विचार पर एकत्रित हो रहे हैं।

यह पोस्ट उन धागों को एक साथ खींचती है।

हार्नेस वास्तव में क्या है?

Trivedy की मुख्य परिभाषा अधिकांश भारी काम करती है:

एजेंट = मॉडल + हार्नेस। यदि आप मॉडल नहीं हैं, तो आप हार्नेस हैं।

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

विशेष रूप से, एक हार्नेस में शामिल है:

• सिस्टम प्रॉम्प्ट, CLAUDE.md, AGENTS.md, स्किल फ़ाइलें, और सबएजेंट निर्देश।
• टूल्स, स्किल्स, MCP सर्वर, और उनके तकनीकी विवरण।
• बंडल किया गया इन्फ्रास्ट्रक्चर, जैसे फ़ाइलसिस्टम, सैंडबॉक्स, और हेडलेस ब्राउज़र।
• सबएजेंट बनाने, हैंडऑफ़ संभालने और मॉडल रूटिंग के लिए ऑर्केस्ट्रेशन तर्क।
• नियतात्मक निष्पादन के लिए हुक्स और मिडलवेयर, जैसे लिंट चेक या कॉन्टेक्स्ट कॉम्पैक्शन।
• लॉग्स, ट्रेसेस, लागत और विलंबता मीटरिंग के लिए ऑब्ज़र्वेबिलिटी टूल्स।

इसके मूल में, एक एजेंट एक ऐसा सिस्टम है जो एक लक्ष्य प्राप्त करने के लिए एक लूप में टूल्स चलाता है। असली कौशल उन टूल्स और उस लूप दोनों को डिज़ाइन करने में है।

जबकि यह एक विशाल सतह क्षेत्र का प्रतिनिधित्व करता है, यह आपका सतह क्षेत्र है, मॉडल प्रदाता का नहीं। Claude Code, Cursor, Codex, Aider, और Cline सभी हार्नेस हैं। अंतर्निहित मॉडल प्लेटफ़ॉर्म पर समान हो सकता है, लेकिन आप जो व्यवहार अनुभव करते हैं, वह हार्नेस द्वारा नियंत्रित होता है।

आइए "स्किल इश्यू" को फिर से परिभाषित करें

यह आम बात है कि जब कोई एजेंट कुछ बेतुका करता है, तो इंजीनियर मॉडल को दोष देते हैं, और अक्सर समस्या को "अगले संस्करण की प्रतीक्षा करें" के रूप में टाल देते हैं।

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

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

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

रैचेट: हर गलती एक नियम बन जाती है

हार्नेस इंजीनियरिंग में सबसे महत्वपूर्ण आदत एजेंट की गलतियों को स्थायी संकेतों के रूप में मानना है - न कि एक बार की घटना जिसे दोबारा प्रयास करके भुला दिया जाए।

यदि कोई एजेंट एक PR भेजता है जिसमें एक कमेंटेड-आउट टेस्ट है जो गलती से मर्ज हो जाता है, तो यह एक इनपुट है। AGENTS.md के अगले पुनरावृत्ति में कहना होगा: "टेस्ट को कभी कमेंट आउट न करें; उन्हें हटाएँ या ठीक करें।" अगले प्री-कमिट हुक को डिफ में .skip( को स्वचालित रूप से फ़्लैग करना चाहिए। समीक्षक सबएजेंट को कमेंटेड-आउट टेस्ट को ब्लॉक करने के लिए अपडेट किया जाना चाहिए।

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

इस वजह से, हार्नेस इंजीनियरिंग एक अनुशासन है, न कि एक सभी के लिए एक-सा फ्रेमवर्क। किसी विशिष्ट कोडबेस के लिए सही हार्नेस पूरी तरह से उसकी अनूठी विफलता के इतिहास द्वारा आकार दिया जाता है।

व्यवहार से पीछे की ओर काम करना

हार्नेस डिज़ाइन करने का सबसे प्रभावी तरीका वांछित व्यवहार से शुरू करना और उस घटक का निर्माण करना है जो इसे प्रदान करता है: हम जो व्यवहार चाहते हैं → उसे प्राप्त करने के लिए हार्नेस डिज़ाइन।

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

फ़ाइलसिस्टम और Git - स्थायी स्थिति

फ़ाइलसिस्टम मौलिक है। मॉडल केवल उसी पर काम कर सकते हैं जो उनके कॉन्टेक्स्ट विंडो में फिट बैठता है। एक फ़ाइलसिस्टम डेटा पढ़ने के लिए एक कार्यक्षेत्र, मध्यवर्ती कार्य को ऑफलोड करने के लिए एक स्थान, और कई एजेंटों के समन्वय के लिए एक सतह प्रदान करता है।

Git जोड़ने से मुफ्त वर्जनिंग मिलती है, जिससे एजेंट प्रगति को ट्रैक कर सकता है, प्रयोगों को ब्रांच कर सकता है, और त्रुटियों को वापस ला सकता है।

Bash और कोड निष्पादन: सामान्य-उद्देश्य टूलिंग

अधिकांश एजेंट ReAct लूप पर काम करते हैं: तर्क करें, टूल कॉल के माध्यम से कार्य करें, निरीक्षण करें, दोहराएं। हर संभावित कार्रवाई के लिए पहले से एक टूल बनाने के बजाय, एजेंट को bash एक्सेस देने से वह अपनी ज़रूरत के अनुसार टूल बना सकता है।

एजेंट आमतौर पर शेल कमांड में उत्कृष्ट होते हैं, जिससे bash और कोड निष्पादन स्वायत्त समस्या-समाधान के लिए डिफ़ॉल्ट रणनीति बन जाती है।

सैंडबॉक्स और डिफ़ॉल्ट टूलिंग

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

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

मेमोरी और सर्च: निरंतर सीखना

मॉडलों के पास अपने प्रशिक्षण भार और वर्तमान कॉन्टेक्स्ट से परे कोई ज्ञान नहीं है। हार्नेस मेमोरी फ़ाइलों (जैसे AGENTS.md) का उपयोग करके इस अंतर को पाटते हैं जो हर सत्र में ज्ञान इंजेक्ट करती हैं।

नए लाइब्रेरी संस्करणों या लाइव डेटा जैसी रीयल-टाइम जानकारी के लिए, वेब सर्च और MCP टूल सीधे हार्नेस में बेक किए जाते हैं।

कॉन्टेक्स्ट रॉट से लड़ना

जैसे-जैसे मॉडलों की कॉन्टेक्स्ट विंडो भरती है, उनमें तर्क करने की क्षमता घटती जाती है। हार्नेस तीन प्राथमिक तकनीकों का उपयोग करके इस कमी का प्रबंधन करते हैं:

• कॉम्पैक्शन: पुराने कॉन्टेक्स्ट को बुद्धिमानी से सारांशित और ऑफलोड करना ताकि API त्रुटियों को रोका जा सके।
• टूल-कॉल ऑफलोडिंग: बड़े टूल आउटपुट (जैसे 2,000-लाइन लॉग) को फ़ाइलसिस्टम में संग्रहीत करना जबकि केवल आवश्यक हेडर और फुटर को कॉन्टेक्स्ट में रखना।
• प्रगतिशील प्रकटीकरण: निर्देशों और टूल्स को तभी प्रकट करना जब कोई कार्य स्पष्ट रूप से उनकी मांग करता है, न कि स्टार्टअप पर सब कुछ लोड करना।

लंबी-अवधि निष्पादन

स्वायत्त, लंबे समय तक चलने वाला कार्य जल्दी रुकने और खराब समस्या अपघटन से ग्रस्त होता है। हार्नेस संरचनात्मक डिज़ाइन के माध्यम से इसका मुकाबला करते हैं:

• लूप्स: मॉडल के बाहर निकलने के प्रयास को रोकना और उसे एक ताजा कॉन्टेक्स्ट विंडो में पूर्णता लक्ष्य के विरुद्ध जारी रखने के लिए मजबूर करना।
• प्लानिंग: मॉडल को लक्ष्यों को एक चरण-दर-चरण योजना फ़ाइल में विघटित करने के लिए मजबूर करना, प्रत्येक चरण के बाद स्व-सत्यापन हुक के माध्यम से अपने काम की जाँच करना।
• स्प्लिट्स: जनरेशन और मूल्यांकन को अलग-अलग एजेंटों में अलग करना, मॉडलों के अपने स्वयं के काम को ग्रेड करते समय अंतर्निहित सकारात्मक पूर्वाग्रह को रोकना।

हुक्स आपकी प्रवर्तन परत हैं

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

आदर्श रूप से, सफलता मौन होती है, और विफलताएँ विस्तृत होती हैं। यदि टाइपचेक पास हो जाता है, तो एजेंट कुछ नहीं सुनता; यदि यह विफल होता है, तो त्रुटि सीधे लूप में वापस इंजेक्ट की जाती है ताकि स्व-सुधार हो सके।

यहाँ नियम पुस्तिका और टूल चयन है

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

वही अनुशासन टूल्स पर लागू होता है। दस अत्यधिक केंद्रित टूल हमेशा पचास ओवरलैपिंग टूल से बेहतर प्रदर्शन करेंगे।

इसके अलावा, क्योंकि टूल विवरण प्रॉम्प्ट को आबाद करते हैं, दुर्भावनापूर्ण या लापरवाह बाहरी एकीकरण (जैसे अप्रमाणित MCP सर्वर) एजेंट के काम शुरू करने से पहले ही उसमें खराब प्रॉम्प्ट इंजेक्ट कर सकते हैं।

उत्पादन में यह कैसा दिखता है

एक परिपक्व हार्नेस की सबसे स्पष्ट सार्वजनिक तस्वीर जो मैंने देखी है, वह है Fareed Khan का (अनुमानित) Claude Code के आर्किटेक्चर का विवरण।

पिछले अनुभाग की लगभग हर अवधारणा इस आरेख पर एक नामित घटक के रूप में दिखाई देती है। कॉन्टेक्स्ट इंजेक्शन ज्ञान परत है। लूप स्टेट मेमोरी स्टोर और वर्कट्री आइसोलेटर में रहता है। विनाशकारी-कार्रवाई हुक्स परमिशन गेट के पीछे बैठते हैं। सबएजेंट कॉन्टेक्स्ट फायरवॉल पूरी मल्टी-एजेंट परत है। टूल डिस्पैच रजिस्ट्री वह जगह है जहाँ MCP सर्वर और bash दोनों प्लग इन होते हैं। Claude Code का प्रक्षेपवक्र कम से कम उतना ही हार्नेस के बारे में है जितना कि इसके नीचे के मॉडल के बारे में।

हार्नेस सिकुड़ते नहीं, वे स्थानांतरित होते हैं

जैसे-जैसे मॉडल बेहतर होते हैं, हार्नेस की आवश्यकता गायब नहीं होती - यह बदल जाती है।

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

हार्नेस का हर घटक एक धारणा को एनकोड करता है कि मॉडल अपने दम पर क्या नहीं कर सकता। जब मॉडल में सुधार होता है, तो पुरानी स्कैफोल्डिंग को हटा दिया जाना चाहिए, और अगले क्षितिज तक पहुँचने के लिए नई स्कैफोल्डिंग का निर्माण किया जाना चाहिए।

प्रशिक्षण लूप के बारे में क्या?

हार्नेस डिज़ाइन और मॉडल प्रशिक्षण के बीच एक सक्रिय फीडबैक लूप है।

आज के मॉडलों को अक्सर लूप में विशिष्ट हार्नेस के साथ पोस्ट-ट्रेन किया जाता है, जिससे कुछ हद तक ओवरफिटिंग होती है। मॉडल उन विशिष्ट कार्यों में असाधारण रूप से अच्छा हो जाता है जिन्हें हार्नेस डिज़ाइनरों ने प्राथमिकता दी (जैसे, फ़ाइलसिस्टम ऑप्स, bash, सबएजेंट डिस्पैच)।

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

हार्नेस-एज़-अ-सर्विस (HaaS)

उद्योग LLM API (जो पूर्णताएँ प्रदान करते हैं) पर निर्माण करने से हार्नेस API (जो एक रनटाइम प्रदान करते हैं) पर निर्माण करने की ओर बढ़ रहा है। SDK अब लूप, टूल्स, कॉन्टेक्स्ट मैनेजमेंट, हुक्स और सैंडबॉक्स सीधे बॉक्स से बाहर प्रदान करते हैं।

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

यही वह चीज़ है जो समस्या निवारण को स्केलेबल बनाती है: आप पूरे एजेंट आर्किटेक्चर को फिर से आविष्कार करने के बजाय एक अच्छी तरह से फैक्टर किए गए कॉन्फ़िगरेशन सतह को ट्यून कर रहे हैं।

यह कहाँ जा रहा है

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

सबसे रोमांचक खुली समस्याएँ एकल एजेंटों से आगे बढ़ रही हैं: समानांतर में कई एजेंटों को ऑर्केस्ट्रेट करना, एजेंटों को हार्नेस-स्तर की विफलताओं को ठीक करने के लिए अपने स्वयं के ट्रेस का विश्लेषण करने में सक्षम बनाना, और ऐसे वातावरण का निर्माण करना जो जस्ट-इन-टाइम टूल्स को गतिशील रूप से इकट्ठा करते हैं।

अंततः, यह वह चरण है जहाँ हार्नेस स्थिर कॉन्फ़िगरेशन फ़ाइलें होना बंद कर देते हैं और कंपाइलरों की तरह अधिक कार्य करना शुरू कर देते हैं।

यदि आप एक शानदार एजेंट हार्नेस फ्रेमवर्क की तलाश में हैं, तो @FredKSchott ने Flue लिखा है। यह ठोस है और स्पष्ट रूप से इस पोस्ट के पुराने संस्करण से प्रेरित था!