2026 में AI एजेंट्स कैसे बनाएं (पूर्ण कोर्स)

यहाँ वह सच्चाई है जो कोई AI बिल्डरों को नहीं बताता।

उनमें से ज़्यादातर डेमो बना रहे हैं

आपको बस यह बनाने की ज़रूरत है

एक प्रोडक्शन-लेवल AI एजेंट

TLDR; अगर आप पढ़ना नहीं चाहते, तो यह लिंक अपने एजेंट को दें और उससे सवाल पूछें: ➡️https://github.com/codejunkie99/agentic-harness

यह वह ट्वीट है जिसने यह सब शुरू किया

समस्या यह है कि ज़्यादातर AI इंजीनियरों को इस बात का स्पष्ट अंदाज़ा नहीं होता कि जब वे एजेंट्स को गंभीरता से लेने का फैसला करते हैं तो वास्तव में क्या बनाना है।

कुछ लोग LangChain की ओर हाथ बढ़ाते हैं क्योंकि YouTube पर मल्टी-एजेंट डेमो साफ-सुथरे लगते हैं, और फिर अगले दो हफ्ते Python इंटरऑप और async रनटाइम बेमेल से लड़ते हुए बिताते हैं, इससे पहले कि वे पूरी चीज़ को खत्म कर दें।

कुछ लोग शुरू से एक कस्टम ऑर्केस्ट्रेशन लेयर बनाने की कोशिश करते हैं: एक लूप, एक सेशन स्टोर, एक कॉन्टेक्स्ट असेंबलर, और असली एजेंट कभी खत्म नहीं कर पाते क्योंकि इन्फ्रास्ट्रक्चर ने टाइमलाइन खा ली।

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

नतीजा आमतौर पर एक जैसा होता है: बहुत सारी प्लंबिंग, कोई प्रोडक्शन एजेंट नहीं, और इस बात का कोई मेंटल मॉडल नहीं कि प्रोडक्शन एजेंट रनटाइम वास्तव में कैसा दिखता है।

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

आपको एक रनटाइम को इतनी गहराई से समझने की ज़रूरत है कि आप एक प्रोडक्शन एजेंट को हैंडलर से लेकर डिप्लॉयमेंट तक अपने कंट्रोल में रख सकें।

इसका मतलब है यह सीखना कि कैसे:

• तीन-लेयर आर्किटेक्चर को वायर करें ताकि आपका हैंडलर लॉजिक प्रोवाइडर स्वैप और टार्गेट बदलावों से बचे, बिना एजेंट कोड को छुए
• सेशन और टास्क का सही तरीके से उपयोग करें ताकि लंबे जॉब अपने ही कॉन्टेक्स्ट को दूषित न करें
• ऐसी भूमिकाएँ और कौशल लिखें जो बिना कुछ रीकंपाइल किए मॉडल के व्यवहार को आकार दें
• कॉम्पैक्शन कॉन्फ़िगर करें ताकि दो घंटे चलने वाले सेशन एक घंटे में ही भ्रमित न होने लगें
• HttpSessionEnv को रिमोट सैंडबॉक्स पर पॉइंट करें ताकि बाइनरी लोकली चले जबकि एक्सीक्यूशन Linux पर चले
• सही बिल्ड टार्गेट चुनें: native, node, या Cloudflare, बिना उनके बीच कोई एजेंट लॉजिक फिर से लिखे
• एडॉप्टर खुद लिखने के बजाय कनेक्टर जनरेट करें, और समझें कि असली लोड के तहत यह अंतर क्यों मायने रखता है

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

यह लेख 4,000+ शब्दों का है और सीधे रिपॉजिटरी और दस्तावेज़ों से लिया गया है, न कि दूसरे हाथ के सारांश या डेमो-स्तरीय उदाहरणों से।

लेकिन इसका असली मूल्य यह है कि हर सेक्शन में एक काम करने वाला कोड स्निपेट, फैसला क्यों लिया गया इसकी स्पष्ट व्याख्या, और वह सटीक विफलता मोड है जिसका सामना आप करेंगे यदि आप इसे छोड़ देते हैं।

इस तरह, जब तक आप पढ़ना खत्म करेंगे, तब तक आप एक प्रोडक्शन एजेंट को पहले हैंडलर से लेकर सैंडबॉक्स तक और CI जॉब तक पूरी तरह से अपने कंट्रोल में रख सकते हैं जो इसे बिना निगरानी के चलाता है।

इस समझ को बनाने में कोडबेस के साथ 6 सप्ताह से अधिक के दैनिक काम लगे, जिसमें से अधिकांश उन चीज़ों को डीबग करने में बीता जो असली परिस्थितियों में टूटने से पहले सही लगती थीं।

अब इसमें गोता लगाते हैं। ⬇️

प्रोजेक्ट का आकार

दो क्रेट। एक बाइनरी। हर एक्सीक्यूशन टार्गेट एक कॉन्फ़िग विकल्प है, फिर से लिखना नहीं।

• SDK एक लाइब्रेरी है जिसे आप किसी भी Rust प्रोजेक्ट में खींच सकते हैं। CLI इसे रैप करता है। आपका एजेंट एक Rust बाइनरी है जो use agentic_harness::prelude::*; से शुरू होती है।
• cargo build पूरी पाइपलाइन है। कोई बंडलर नहीं। कोई ट्रांसपाइल स्टेप नहीं। टार्गेट मशीन पर कोई लैंग्वेज रनटाइम नहीं। एक सेल्फ-कंटेंड एक्ज़ीक्यूटेबल प्लस एक manifest.json।

डिज़ाइन की बाध्यता जिसने सब कुछ संचालित किया: एक ही एजेंट बाइनरी को आपके लैपटॉप पर इंटरैक्टिव मोड में, GitHub Actions जॉब में एक नया रिपो चेकआउट करते हुए, HTTP पर एक रिमोट E2B सैंडबॉक्स के खिलाफ, और Cloudflare Worker बाउंड्री पर बिना उनके बीच एजेंट लॉजिक की एक भी लाइन बदले चलना चाहिए।

इस कोडबेस का हर फैसला उस बाध्यता का सम्मान करने के लिए मौजूद है।

3 लेयर और उनमें से प्रत्येक क्यों मौजूद है

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

आपका Rust कोड बाहरी वलय है।

• आप हैंडलर लिखते हैं। हैंडलर एक AgentContext प्राप्त करते हैं। वे सेशन को कॉल करते हैं। सेशन मॉडल को कॉल करते हैं, फ़ाइलें पढ़ते हैं, फ़ाइलें लिखते हैं, शेल कमांड चलाते हैं, टास्क स्पॉन करते हैं, MCP सर्वर से कनेक्ट होते हैं।
• आप कभी सीधे HTTP क्लाइंट को नहीं छूते। आप कभी सीधे मॉडल रिस्पॉन्स को पार्स नहीं करते। SDK दोनों को संभालता है।

हार्नेस मध्य वलय है।

• यह एजेंट रजिस्ट्री का प्रबंधन करता है, URL पथ द्वारा पहचान को रूट करता है, कॉल के बीच सेशन पर्सिस्टेंस, सेशन बढ़ने पर कॉन्टेक्स्ट कॉम्पैक्शन, भूमिका और कौशल खोज, मॉडल चयन प्राथमिकता, और प्रोवाइडर-न्यूट्रल ModelClient ट्रेट को संभालता है।
• यह आपको हैंडलर कोड को छुए बिना Anthropic को OpenAI या स्थानीय Ollama इंस्टेंस से बदलने देता है।
• हार्नेस ही आपके एजेंट लॉजिक को प्रोवाइडर और टार्गेट में पुन: प्रयोज्य बनाता है।
• यह वह जगह भी है जहाँ वे सभी चीज़ें संभाली जाती हैं जो प्रोडक्शन में टूटती हैं - सेशन स्टेट, कॉन्टेक्स्ट ओवरफ़्लो, प्रोवाइडर विफलताएँ, समवर्ती अनुरोध ऑर्डरिंग।

एक्सीक्यूशन टार्गेट आंतरिक वलय हैं।

• स्थानीय फ़ाइलसिस्टम। CI चेकआउट। HttpSessionEnv जो Daytona या E2B पर पॉइंट करता है। Cloudflare Worker बाउंड्री।
• हार्नेस को इस बात से कोई फर्क नहीं पड़ता कि आप किसका उपयोग कर रहे हैं। आपके हैंडलर को भी नहीं। वे session.shell() और session.write() कॉल करते हैं और हार्नेस उन्हें अंतर्निहित टार्गेट की ज़रूरत के अनुसार अनुवादित करता है।
• यह अलगाव पूरी बात है। जब E2B एक नया API वर्जन जारी करता है, तो आप कनेक्टर को अपडेट करते हैं, अपने एजेंट लॉजिक को नहीं।
• जब Anthropic claude-opus-4-7 शिप करता है, तो आप runtime.json को अपडेट करते हैं, अपने हैंडलर को नहीं। बाहरी वलय साफ रहता है क्योंकि मध्य वलय सारे बदलाव को सोख लेता है।

runtime config: वह फ़ाइल जो मॉडल लेयर को नियंत्रित करती है

एक भी हैंडलर लिखने से पहले, आपको अपने वर्कस्पेस में runtime.json चाहिए।

इसे .agentic-harness/config.json या वर्कस्पेस रूट पर agentic-harness.json के रूप में रखें। load_workspace_context() इसे स्वचालित रूप से उठा लेता है।

रनटाइम पर मॉडल चयन इस प्राथमिकता का पालन करता है:

1. PromptOptions::model(...) : प्रति-कॉल ओवरराइड
2. चयनित भूमिका का मॉडल मेटाडेटा : प्रति-भूमिका डिफ़ॉल्ट
3. runtime config से defaultModel : वर्कस्पेस डिफ़ॉल्ट

समझने वाली बात: मॉडल ID का उपयोग करने से पहले उसे पंजीकृत होना चाहिए। openaiCompatibleModels वह सूची है जिसका उपयोग हार्नेस बिल्ट-इन chat-completions क्लाइंट को वायर करने के लिए करता है। यदि आपका मॉडल उस सूची में नहीं है, तो आपको सेशन के बीच में भ्रमित करने वाली विफलता के बजाय स्टार्टअप पर एक साफ त्रुटि मिलती है।

OpenAI-संगत गेटवे के लिए, कॉन्फ़िग एक जैसा दिखता है। baseUrl को अपने गेटवे पर पॉइंट करें:

• runtime.json में कभी शाब्दिक API key न लिखें। apiKeyEnv का उपयोग करें और असली key को अपने एनवायरनमेंट में रखें।
• हार्नेस एनव वेरिएबल को अनुरोध के समय पढ़ता है, स्टार्टअप पर नहीं - जिसका मतलब है कि आप सर्वर को पुनरारंभ किए बिना keys को घुमा सकते हैं।

एजेंट की पहचान एक URL पथ है, कभी रजिस्ट्री लुकअप नहीं

यह पहला डिज़ाइन निर्णय था जिसने मुझे आश्चर्यचकित किया। अब मुझे लगता है कि यह सही है।

कोई एजेंट ID सिस्टम नहीं है। कोई रजिस्ट्री key नहीं। कोई UUID नहीं जो आप खुद जनरेट करते हैं। आपके एजेंट की पहचान POST /agents/<name>/<id> है।

• हार्नेस उस URL के पीछे सभी सेशन स्टेट बुककीपिंग को संभालता है।
• यह काम करने का कारण: हर सिस्टम में हर कॉलर पहले से जानता है कि कॉन्टेक्स्ट से एक सार्थक ID कैसे बनाई जाए। एक PR नंबर। एक run ID। एक टास्क नाम के साथ संयुक्त टाइमस्टैम्प। एक यूज़र हैंडल।
• आपको सेशन क्रिएशन एंडपॉइंट की ज़रूरत नहीं है। आपको सेशन ID को अलग से स्टोर करने की ज़रूरत नहीं है। URL ही सेशन है।

Rust साइड पर एजेंट हैंडलर कॉलर द्वारा प्रदान की गई ID प्राप्त करने के लिए ctx.id() कॉल करता है:

सेशन: स्टेटफुल एक्सीक्यूशन कॉन्टेक्स्ट

एक सेशन एक बातचीत के धागे से अधिक है। यह एक एजेंट इनवोकेशन के लिए पूर्ण एक्सीक्यूशन कॉन्टेक्स्ट है।

इसमें शामिल है:

• मॉडल के साथ संदेश इतिहास
• वर्कस्पेस फ़ाइल एक्सेस (पढ़ना, लिखना, संपादित करना, grep, glob, stat, readdir)
• cwd और env नियंत्रण के साथ शेल एक्सीक्यूशन
• टूल रजिस्ट्रेशन (MCP सर्वर, कस्टम टूल)
• निर्धारित भूमिका और उसका सिस्टम प्रॉम्प्ट ओवरले
• कॉम्पैक्शन बजट और हिस्ट्री वॉटरमार्क

आपको ctx.session_with_id() कॉल करके एक सेशन मिलता है, जिसमें कोई भी ID समझ में आती है:

• जब आप एक ही ID का उपयोग करते हैं तो सेशन HTTP कॉल के बीच बने रहते हैं। एक ही सेशन ID के साथ एक ही एजेंट एंडपॉइंट को तीन बार कॉल करें, मॉडल तीनों आदान-प्रदान को एक सतत बातचीत के रूप में देखता है।
• इतिहास स्वचालित रूप से जमा होता है। आप इसे प्रबंधित नहीं करते।
• यही बात मल्टी-स्टेप वर्कफ़्लो को बिना खुद स्टेट मैनेज किए संभव बनाती है। आप session.prompt() कॉल करते रहते हैं और हार्नेस बाकी सब संभालता है।

जब आपको एक प्रॉम्प्ट के साथ बड़ी मात्रा में कॉन्टेक्स्ट पास करने की आवश्यकता हो, तो फ़ाइल पढ़ें और इसे इनलाइन फ़ॉर्मेट करें:

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

टास्क: फोकस्ड चाइल्ड सेशन जो पैरेंट को साफ रखते हैं

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

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

नियम: यदि उप-समस्या का एक स्पष्ट डिलिवरेबल है और उसे पूरा करने के लिए पैरेंट के वार्तालाप इतिहास की आवश्यकता नहीं है, तो इसे एक टास्क बनाएं। "इसे टास्क बनाएं" की सीमा आपके विचार से कम है।

कोडबेस में समानांतर विश्लेषण के लिए: कार्टोग्राफर पैटर्न, टास्क को फैन आउट करें और परिणाम एकत्र करें:

प्रत्येक टास्क साफ है। प्रत्येक टास्क बिल्कुल एक निर्देशिका पर केंद्रित है। पैरेंट सेशन परिणाम एकत्र करता है और अंतिम दस्तावेज़ लिखता है।

यदि आपके पास 12 मॉड्यूल हैं, तो आप 12 केंद्रित टास्क चलाते हैं, प्रत्येक दूसरे से शून्य बोझ के साथ शुरू होता है।

भूमिकाएँ और कौशल: बिना रीकंपाइल किए व्यवहार को आकार देना

1. भूमिकाएँ .agentic-harness/roles/ में रहती हैं। कौशल .agents/skills/ में रहते हैं। जब हार्नेस शुरू होता है तो दोनों स्वचालित रूप से खोजे जाते हैं।
2. भूमिकाएँ सिस्टम-प्रॉम्प्ट ओवरले हैं जो एक कॉल के दायरे में होती हैं। कॉल के समय लागू होती हैं और बाद में हटा दी जाती हैं। वे संदेश इतिहास में बनी नहीं रहती हैं। वे कॉल के बीच जमा नहीं होती हैं।

प्राथमिकता श्रृंखला: कॉल भूमिका > सेशन भूमिका > एजेंट भूमिका > कोई भूमिका नहीं।

• मॉडल फ्रंटमैटर वैकल्पिक लेकिन उपयोगी है। यह आपको विशिष्ट भूमिकाओं को विशिष्ट मॉडलों पर रूट करने देता है।
• आपकी एक्सप्लेनर भूमिका गति और लागत के लिए claude-sonnet-4-6 पर चलती है। आपकी सुरक्षा-ऑडिटर गहराई के लिए claude-opus-4-7 पर चलती है। आप इसे भूमिका फ़ाइल में एक बार कॉन्फ़िगर करते हैं और फिर कभी इसके बारे में नहीं सोचते।
• कौशल व्यवहार विवरणक फ़ाइलें हैं जिन्हें मॉडल एक सेशन की शुरुआत में पढ़ता है।
• वे .agents/skills/ में मार्कडाउन फ़ाइलें हैं। हार्नेस उन्हें स्वचालित रूप से ढूंढ लेता है। आप उन्हें कहीं पंजीकृत नहीं करते।

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

मॉडल इसे हर सेशन से पहले पढ़ता है। आप मार्कडाउन संपादित करते हैं। अगले रन पर व्यवहार अपडेट हो जाता है। कोई रीकंपाइल नहीं।

मॉडल इसे पढ़ता है। यह ऐसे कमिट लिखता है जो आपके कन्वेंशन से मेल खाते हैं। आप इसे हर सेशन में याद नहीं दिलाते। आप एक फ़ाइल बनाए रखते हैं।

कोडिंग एजेंट लूप पूर्ण विवरण में

कोडिंग एजेंट लूप प्राथमिक उपयोग मामला है जिसके आसपास CLI बनाया गया था। यह वह जगह भी है जहाँ सबसे अधिक चीज़ें गलत हो सकती हैं यदि आप इसे गलत कॉन्फ़िगर करते हैं।

सभी महत्वपूर्ण विकल्पों के साथ पूर्ण कमांड:

प्रत्येक फ़्लैग क्या करता है और यह क्यों मायने रखता है:

1. --workspace . रूट सेट करता है। सभी फ़ाइल ऑपरेशन यहाँ सैंडबॉक्स किए गए हैं। एजेंट इस पथ के बाहर पढ़ या लिख नहीं सकता, हार्नेस स्तर पर लागू किया गया - मॉडल पर भरोसा करके नहीं कि वह खुद को प्रतिबंधित करेगा।
2. --llm auto आपके runtime config में defaultModel से मॉडल चुनता है। जटिल कार्यों के लिए जिन्हें गहन तर्क की आवश्यकता है, --llm anthropic/claude-opus-4-7 का उपयोग करें, या तेज़ पुनरावृत्ति के लिए --llm anthropic/claude-sonnet-4-6 का उपयोग करें।
3. --deny-path एक हार्ड ब्लॉक है। यह प्रीफ़िक्स-शैली से मेल खाता है, इसलिए --deny-path config/ config/ के तहत सब कुछ कवर करता है। पहले रन से पहले अपने वर्कस्पेस का ऑडिट करें और हर उस पथ को सूचीबद्ध करें जिसमें रहस्य या प्रोडक्शन कॉन्फ़िग है - सिर्फ .env नहीं।
4. --approve-dependencies मानव अनुमोदन चरण के बिना Cargo.toml संशोधनों की अनुमति देता है। यदि आप प्रत्येक नए क्रेट को जोड़े जाने से पहले समीक्षा करना चाहते हैं तो इसे छोड़ दें।
5. --commit सभी परिवर्तनों को स्वचालित रूप से स्टेज करता है और आपके द्वारा प्रदान किए गए संदेश के साथ एक सफल रन के अंत में उन्हें कमिट करता है। इस फ़्लैग के बिना, परिवर्तन आपकी समीक्षा के लिए अनस्टेज्ड संशोधनों के रूप में आते हैं।
6. --pr कमिट से एक पुल रिक्वेस्ट खोलता है। रन से पहले एक साफ git स्थिति और एक वास्तविक शाखा की आवश्यकता है, न कि डिटैच्ड HEAD।

लूप स्वयं: Inspect → Brief → LLM + Tools → Edit + Test → Commit · PR।

• inspect: वर्कस्पेस संरचना पढ़ता है, कौशल और भूमिकाएँ लोड करता है, प्रॉम्प्ट से सबसे अधिक प्रासंगिक फ़ाइलों की पहचान करता है।
• कोई भी कोड छूने से पहले अपनी समझ coding-brief.md में लिखता है।
• brief: मॉडल एक योजना के लिए प्रतिबद्ध होता है। आप यह देखने के लिए रन के बीच में .agentic-harness/runs/<id>/coding-brief.md पढ़ सकते हैं कि उसने क्या तय किया।
• यदि ब्रीफ गलत लगता है, तो रन को मार दें। एक स्पष्ट प्रॉम्प्ट के साथ पुनरारंभ करना एजेंट को एक बुरी योजना को निष्पादित करने देने से सस्ता है।
• LLM + tools: एडिट-टेस्ट लूप। मॉडल बदलाव करता है, टेस्ट सूट चलाता है, आउटपुट पढ़ता है, और अधिक बदलाव करता है। तब तक पुनरावृत्ति करता है जब तक टेस्ट पास नहीं हो जाते, पुनरावृत्ति सीमा नहीं मारी जाती, या यह तय नहीं करता कि कार्य पूरा हो गया है।

commit · PR: स्टेज करता है, कमिट करता है, पुश करता है, संलग्न डिफ के साथ PR खोलता है।

प्रत्येक रन .agentic-harness/runs/<id>/ में छह आर्टिफैक्ट लिखता है:

1. coding-brief.md : वह योजना जिसके लिए एजेंट कोई कोड लिखने से पहले प्रतिबद्ध हुआ
2. summary.md : क्या किया गया, क्या प्रयास किया गया, और क्यों, इसका मानव-पठनीय विवरण
3. run.json : संरचित मेटाडेटा: उपयोग किया गया मॉडल, कुल अवधि, इनपुट/आउटपुट टोकन गणना, पुनरावृत्ति गणना, अंतिम निकास स्थिति
4. events.jsonl : पूर्ण इनपुट और आउटपुट के साथ क्रम में हर एक टूल कॉल, यह डीबग करने के लिए कि क्या गलत हुआ
5. diff.patch : सभी फ़ाइल परिवर्तनों का पूर्ण डिफ
6. checks.json : अंतिम परीक्षण और लिंट परिणाम जिन्होंने सफलता या विफलता निर्धारित की

याद रखने योग्य टिप्स

• इन्हें क्षणिक आउटपुट के बजाय संरचित लॉग के रूप में मानें। मैं किसी भी कार्य के लिए रन आर्टिफैक्ट को रिपॉजिटरी में कमिट करता हूँ जिसे मुझे पुन: प्रस्तुत करने में सक्षम होने की आवश्यकता है।
• अकेला run.json ~2KB, आपको मॉडल, टोकन लागत, और यह बताता है कि क्या यह सफल हुआ। events.jsonl आपको बताता है कि एजेंट ने वास्तव में क्या किया और किस क्रम में, जब आपको एक खराब रन को डीबग करने की आवश्यकता हो।

CI के लिए, पैटर्न है:

HttpSessionEnv: बाइनरी को स्थानीय रूप से चलाना, दूरस्थ रूप से निष्पादित करना

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

use agentic_harness::HttpSessionEnv;

वायर प्रोटोकॉल HTTP पर JSON है। हर ऑपरेशन:

1. exec
2. read
3. write
4. edit
5. grep
6. glob
7. stat
8. readdir
9. mkdir
10. rm का एक परिभाषित अनुरोध/प्रतिक्रिया आकार है।

कोई भी सैंडबॉक्स जो इस प्रोटोकॉल को लागू करता है, HttpSessionEnv टार्गेट के रूप में काम करता है।

एक नामित सैंडबॉक्स को वायर करने के लिए:

बिल्ट-इन कनेक्टर Vercel Sandbox, Daytona, और E2B के लिए auth और लाइफसाइकिल बॉयलरप्लेट को संभालते हैं:

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

प्रदर्शन के बारे में कोई आपको चेतावनी नहीं देता: HttpSessionEnv पर हर शेल कॉल एक नेटवर्क राउंड ट्रिप है। तंग लूप: एडिट, टेस्ट, आउटपुट चेक करें, एडिट: तेजी से विलंबता जमा करते हैं।

एक 40-पुनरावृत्ति लूप जो स्थानीय रूप से 5 सेकंड लेता है, एक रिमोट सैंडबॉक्स के खिलाफ कई मिनट लेता है यदि प्रत्येक पुनरावृत्ति तीन अलग-अलग शेल कॉल करती है।

फिक्स: शेल कार्य को स्क्रिप्ट में बैच करें।

प्रति पुनरावृत्ति एक कॉल तीन के बजाय। स्क्रिप्ट एक बार लिखें, इसे बार-बार चलाएं। 40-पुनरावृत्ति लूप पर विलंबता अंतर वास्तविक है।

बिल्ड टार्गेट: एक ही कोडबेस, तीन डिप्लॉयमेंट आकार

native डिफ़ॉल्ट है। एक बाइनरी। एक मेनिफेस्ट। टार्गेट मशीन पर और कुछ नहीं। कहीं भी चलता है जो एक नेटिव Linux बाइनरी को निष्पादित कर सकता है।

node होस्टिंग प्लेटफ़ॉर्म के लिए है जिन्हें Node एंट्रीपॉइंट की आवश्यकता होती है। बिल्ड server.mjs जनरेट करता है जो नेटिव Rust बाइनरी को चाइल्ड प्रोसेस के रूप में शुरू करता है और HTTP को प्रॉक्सी करता है। एजेंट लॉजिक अभी भी Rust के रूप में चलता है। Node लेयर एक 30-लाइन HTTP शिम है।

Cloudflare एज डिप्लॉयमेंट के लिए है।

• बिल्ड एक Worker बाउंड्री फ़ाइल और एक Worker-संगत ऐप एडॉप्टर जनरेट करता है।
• हैंडलर WASM JSON ABI के माध्यम से WASM में कंपाइल होते हैं।
• Durable Object बाइंडिंग Cloudflare KV के माध्यम से सेशन पर्सिस्टेंस को संभालती हैं।

Cloudflare के बारे में महत्वपूर्ण बाधा: Workers लंबे समय तक चलने वाले शेल कमांड का समर्थन नहीं करते। उनके पास वास्तविक फ़ाइलसिस्टम नहीं है।

वे cargo या किसी भी बिल्ड टूलिंग का समर्थन नहीं करते। --target cloudflare वेबहुक हैंडलिंग, रूट मेटाडेटा, छोटे कंट्रोल एंडपॉइंट, और Durable Object रूटिंग के लिए है, कोडिंग कार्य के लिए नहीं।

किसी भी चीज़ के लिए जिसे cargo test चलाने की आवश्यकता है, एक नेटिव प्रोसेस या रिमोट सैंडबॉक्स को डेलिगेट करें।

व्यावहारिक निर्णय मैट्रिक्स:

• एक एजेंट को API के रूप में शिप करना जिसे अन्य सेवाएँ कॉल करती हैं → nginx या प्रबंधित प्लेटफ़ॉर्म के पीछे native
• Railway, Render, या किसी प्लेटफ़ॉर्म पर होस्ट करना जो Node की अपेक्षा करता है → node
• वेबहुक इन्जेशन, हल्का रूटिंग, Durable Object स्टेट प्रबंधन → cloudflare
• बाकी सब कुछ → native

स्कीमा-निर्देशित आउटपुट: मॉडल प्रतिक्रियाओं से टाइप किए गए Rust स्ट्रक्ट

मॉडल से JSON लौटाने के लिए कहना और उम्मीद करना कि वह करेगा, आधा समाधान है।

हार्नेस द्वारा इसे निकालना, मान्य करना, और आपके Rust स्ट्रक्ट में डीसेरियलाइज़ करना पूर्ण समाधान है।

मॉडल एक ही प्रतिक्रिया में टाइप किए गए पेलोड के साथ तर्क गद्य भी लौटा सकता है। हार्नेस परिणाम ब्लॉक को

• --RESULT_START--- और ---RESULT_END--- मार्करों के बीच निकालता है। आपको एक Rust स्ट्रक्ट मिलता है। मॉडल आउटपुट से आपके हैंडलर लॉजिक तक कंपाइल-टाइम टाइप सुरक्षा।
• स्कीमा दो काम करती है: यह मॉडल को बताती है कि क्या आकार तैयार करना है, और यह हार्नेस को डीसेरियलाइज़ेशन से पहले मान्य करने के लिए कुछ देती है।
• यदि मॉडल ऐसा कुछ लौटाता है जो स्कीमा से मेल नहीं खाता, तो आपको तीन कॉल साइट बाद में जब आप एक लापता फ़ील्ड तक पहुँचते हैं तो पैनिक के बजाय PromptError::SchemaValidationFailed मिलता है।

MCP टूल: सैंडबॉक्स के बाहर पहुँचना

जब एजेंट को फ़ाइल और शेल से परे क्षमताओं की आवश्यकता होती है, तो connect_mcp एस्केप हैच है।

एजेंट को MCP सर्वर का पूर्ण टूल सेट मिलता है। लिखने के लिए कोई टूल परिभाषाएँ नहीं। विवरण सर्वर से आते हैं। मॉडल तय करता है कि उन विवरणों के आधार पर कब किस टूल को कॉल करना है।

आप एक सेशन में कई MCP सर्वर वायर कर सकते हैं:

• मॉडल अपने विवरणों के आधार पर टूल कॉल करता है। "sentry खोजें" जैसा अस्पष्ट विवरण असंगत रूप से कॉल किया जाता है।
• एक विवरण जो कहता है "त्रुटियों, घटनाओं, या उत्पादन समस्याओं के बारे में किसी भी प्रश्न का उत्तर देने से पहले इसे कॉल करें" विश्वसनीय रूप से कॉल किया जाता है।
• यदि आप MCP सर्वर को नियंत्रित करते हैं, तो निर्देशात्मक विवरण लिखें: मॉडल को बताएं कि कब कॉल करना है, न कि केवल यह कि यह क्या लौटाता है।

कनेक्टर: एडॉप्टर लिखने के बजाय उन्हें जनरेट करना

एक अपरिचित API के खिलाफ हाथ से एडॉप्टर कोड लिखने के बजाय, अपने कोडिंग एजेंट को एक कनेक्टर रेसिपी पाइप करें:

• कनेक्टर रेसिपी सैंडबॉक्स API और SessionEnv अनुबंध का एक संरचित विवरण है जिसे इसे संतुष्ट करने की आवश्यकता है।
• कोडिंग एजेंट इसे पढ़ता है, Rust एडॉप्टर मॉड्यूल लिखता है, प्रमाणीकरण संभालता है, प्रोवाइडर लाइफसाइकिल को रैप करता है, और इसे HttpSessionEnv के रूप में उजागर करता है।
• आप डिफ की समीक्षा करते हैं। आप इसे मर्ज करते हैं। एडॉप्टर आपके प्रोजेक्ट में रहता है। यह अब आपका कोड है।

मैंने इसका उपयोग करके लगभग 20 मिनट में पूर्ण समीक्षा चक्र सहित Daytona को वायर किया। एजेंट को पहले पास पर auth हेडर फ़ॉर्मेट सही मिला।

Daytona दस्तावेज़ों के खिलाफ शुरू से एडॉप्टर लिखने में अधिकांश दोपहर और रिफ्रेश टोकन प्रवाह के बारे में कम से कम दो गलत धारणाएँ लगतीं।

एक बार कनेक्टर जनरेट हो जाने के बाद:

स्वचालित कॉम्पैक्शन: लंबे सेशन को बिना कॉन्टेक्स्ट खोए संभालना

लंबे समय तक चलने वाले सेशन इतिहास जमा करते हैं।

अंततः वे मॉडल की कॉन्टेक्स्ट विंडो को ओवरफ़्लो कर देते हैं।

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

context_window_tokens सेशन के लिए कुल बजट है।

• reserve_tokens वह है जो आप मॉडल की प्रतिक्रिया के लिए रोकते हैं। इतिहास के लिए प्रभावी सीमा context_window_tokens - reserve_tokens है।
• keep_recent_messages पूंछ पर संदेशों की संख्या है जो कॉम्पैक्शन की परवाह किए बिना हमेशा शब्दशः संरक्षित रहते हैं।

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

वह सारांश मध्य भाग को बदल देता है। पूंछ के संदेश बरकरार रहते हैं। कॉम्पैक्ट किया गया सेशन छोटा होता है और अगली कॉल बजट के भीतर फिट बैठती है।

ट्रेडऑफ़ वास्तविक है: सारांश सटीकता खो देते हैं। 50 संदेश पहले किया गया एक विशिष्ट निर्णय: "हमने authlib चुना क्योंकि यह एकमात्र लाइब्रेरी है जिसमें PKCE समर्थन है जो axum के मिडलवेयर मॉडल के साथ काम करता है": सारांश में "हमने auth के लिए authlib चुना" के रूप में जीवित रह सकता है।

यदि वह सटीकता सेशन में बाद में निर्णयों के लिए भार वहन करने वाली है, तो इसे स्पष्ट रूप से संग्रहीत करें:

• निर्णयों को फ़ाइलों में लिखें। फ़ाइलें कॉम्पैक्शन से बच जाती हैं। मॉडल उन्हें मांग पर वापस पढ़ सकता है। यदि वर्कस्पेस सब कुछ वहन करता है तो इतिहास को सब कुछ ले जाने की आवश्यकता नहीं है।
• अपने मॉडल की वास्तविक रिपोर्ट की गई कॉन्टेक्स्ट विंडो देखने के लिए agentic-harness doctor चलाएँ। context_window_tokens को उस मान के 80-90% पर सेट करें।
• टोकन काउंटर मॉडल पक्ष पर पूरी तरह से सटीक नहीं है, और एक एकल बड़ी फ़ाइल रीड आपको 99% पर बैठे होने पर आगे धकेल सकती है।

किन बातों का ध्यान रखें

1. सेशन हिस्ट्री संदूषण

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

1. भूमिका प्राथमिकता आश्चर्य

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

1. --deny-path अंतराल

• समस्या: आप .env को अस्वीकार करते हैं। आपके रहस्य .env.local और config/staging.yaml में भी रहते हैं। एजेंट उनमें से एक को पढ़ता है
• फिक्स: फ़ाइलनाम नहीं, प्रीफ़िक्स को अस्वीकार करें। --deny-path config/ इसके तहत सब कुछ कवर करता है

1. CI में डिटैच्ड HEAD

• समस्या: एजेंट संपादित करता है, टेस्ट पास होते हैं, कमिट विफल होता है - क्योंकि कमिट करने के लिए कोई शाखा नहीं है
• फिक्स: हार्नेस को लागू करने से पहले git checkout -b agent-run-$RUN_ID

1. तंग लूप में HttpSessionEnv विलंबता

• समस्या: तीन शेल कॉल प्रत्येक पर 40 पुनरावृत्तियाँ शुद्ध नेटवर्क विलंबता के मिनट हैं
• फिक्स: agent-check.sh लिखें जो एक आह्वान में सब कुछ करता है। प्रति पुनरावृत्ति एक कॉल

1. कॉन्टेक्स्ट बजट कम आकलन

• समस्या: कॉम्पैक्शन कार्य के बीच में फायर करता है। मॉडल अपनी योजना खो देता है और सारांश से सुधार करना शुरू कर देता है
• फिक्स: वास्तविक विंडो प्राप्त करने के लिए agentic-harness doctor चलाएँ। बजट को उसके 80-90% पर सेट करें

1. हैंडलर पंजीकरण के बाद runtime config लोड हुआ

• समस्या: load_workspace_context() से पहले एक हैंडलर चलता है। कोई मॉडल रजिस्टर्ड नहीं है। एरर कॉन्फ़िग समस्या जैसी नहीं दिखती।
• समाधान: किसी भी एजेंट को वायर करने से पहले app() में हमेशा load_workspace_context() को कॉल करें।

1. --llm रनों के बीच ऑटो बदलता है

• समस्या: defaultModel अपडेट हो जाता है। छह महीने के अंतर पर दो रन तुलनीय नहीं होते। आप पहले रन को दोबारा नहीं बना सकते।
• समाधान: किसी भी चीज़ के लिए जिसे पुनरुत्पादन की आवश्यकता है, runtime.json में मॉडल को पिन करें।

1. रन आर्टिफैक्ट्स को डिलीट करना

• समस्या: आप gitignore नियम में runs/ को साफ़ करते हैं। तीन हफ्ते बाद आपको एक रिग्रेशन दोबारा बनाना होता है और सब कुछ गायब होता है।
• समाधान: किसी भी कार्य के लिए जिसे आपको दोबारा बनाना है, रन आर्टिफैक्ट्स को कमिट करें। run.json 2KB का है। इसे रखें।

चीज़ें जो मैं अलग तरीके से करता

1. कुछ भी छूने से पहले agentic-harness गाइड चलाएँ।
2. हैंडलर लॉजिक लिखने से पहले सेशन-लेवल टेस्ट लिखें।
3. हर उस चीज़ के लिए टास्क का उपयोग करें जिसमें सब-डिलीवरेबल हो।
4. पहले गंभीर रन से मॉडल को पिन करें।
5. निर्णयों को फ़ाइलों में स्टोर करें, सेशन हिस्ट्री में नहीं।
6. रिमोट सैंडबॉक्स का उपयोग करते समय शुरू से ही शेल ऑपरेशन को बैच करें।

मुख्य बात

अधिकांश एजेंट फ्रेमवर्क एक API कॉल के चारों ओर रैपर होते हैं। यह एक रनटाइम है।

एक रैपर "मॉडल को रिस्पॉन्ड कराओ" को हल करता है। एक रनटाइम हल करता है "एक एजेंट को प्रोडक्शन में भेजो और उसे काम करते रखो जब मॉडल बदलता है, सैंडबॉक्स बदलता है, कोडबेस बदलता है, सेशन दो घंटे चलता है और कॉन्टेक्स्ट विंडो ओवरफ्लो हो जाती है।"

3-लेयर आर्किटेक्चर

1. आपका कोड
2. हार्नेस
3. एक्ज़ीक्यूशन टार्गेट

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

जो चीज़ें नहीं बदलतीं: हैंडलर लॉजिक, सेशन स्ट्रक्चर, टास्क पैटर्न, रोल डेफ़िनिशन, स्किल फ़ाइलें। जो चीज़ें बदलती हैं: मॉडल, प्रोवाइडर, सैंडबॉक्स वेंडर, डिप्लॉय टार्गेट।

आर्किटेक्चर इस तरह डिज़ाइन किया गया है कि जो चीज़ें बदलती हैं वे कभी उन चीज़ों को नहीं छूतीं जो नहीं बदलतीं।

यही दांव है। यह सही दांव है।

उम्मीद है आपको यह पढ़ने और यह जानने में मज़ा आया कि मैं एजेंटों और सामान्य रूप से कैसे बनाता हूँ ❣️

अस्वीकरण

यह लेख लेखक द्वारा शोध और लिखा गया था, Minimax-M2.7 द्वारा संपादित। थंबनेल Pinterest से लिया गया था।

Harrison Chase "मेमोरी को खुला होना चाहिए!" —

[https://x.com/hwchase17/status/2046308913939919232Harrison](https://x.com/hwchase17/status/2046308913939919232Harrison)

Chase :"आपका हार्नेस, आपकी मेमोरी" —

[https://www.langchain.com/blog/your-harness-your-memory](https://www.langchain.com/blog/your-harness-your-memory)

Vivek Trivedi :"एक एजेंट हार्नेस की शारीरिक रचना" —

[https://www.langchain.com/blog/the-anatomy-of-an-agent-harness](https://www.langchain.com/blog/the-anatomy-of-an-agent-harness)