पिछले नवंबर मैंने एक क्लाइंट को Claude-powered एजेंट दिया जो incoming support tickets को अलग करने वाला था, उन्हें सही डिपार्टमेंट में भेजने वाला था, और पहले जवाब का ड्राफ्ट बनाने वाला था। मुझे इसे बनाने में तीन हफ्ते लगे। Staging में शानदार दिखा। प्रोडक्शन का पहला दिन ही इसने एक ऐसी रिफंड पॉलिसी बना दी जो मौजूद ही नहीं थी, सत्रह tickets को गलत queue में भेज दिया, और आत्मविश्वास से एक कस्टमर को बता दिया कि उनका ऑर्डर "गुरुवार" तक आ जाएगा, जबकि उसके पास शिपिंग डेटा का कोई एक्सेस नहीं था।
तो। मुझे कुछ सीख मिली।
यह पोस्ट इस बारे में है कि मुझे अब क्या पता है, उस एजेंट को सही तरीके से फिर से बनाने के बाद और तब से कई और भेजने के बाद। कोई थ्योरी नहीं। वास्तविक फैसले जो मैंने लिए, जो टूल्स मैंने चुने, और जिन गलतियों को दोहराऊँगा नहीं। अगर आप कोई एजेंसी ओनर हैं या फ्रीलांसर हैं जो Claude Agent SDK के साथ डेमो स्टेज के आगे जाने की कोशिश कर रहे हैं, तो यह आपके लिए लिखा गया है।
---
Claude Agent SDK सच में क्या है (और क्या नहीं)
किसी भी चीज़ से पहले: SDK कोई जादू नहीं है। यह Claude को tools की एक्सेस देने, multiple turns में conversation context को संभालने, और एक decision loop को orchestrate करने का एक structured तरीका है। Claude किसी task के बारे में सोचता है, फैसला करता है कि tool कॉल करना है या नहीं, नतीजा वापस पाता है, फिर से सोचता है, और फिर दूसरा tool कॉल करता है या कोई final answer देता है।
यह loop सरल दिखता है। असल में सरल है। Complexity पूरी तरह इसके चारों ओर जो कुछ आप रखते हैं, उसमें रहती है।
SDK आपको plumbing देता है। पानी का दबाव, पाइप का व्यास, और यह कि आपने drilling शुरू करने से पहले mains को बंद किया या नहीं, यह सब अभी भी आपकी ज़िम्मेदारी है। मैंने एजेंसी ओनर्स को देखा है जिन्होंने SDK को junior dev को दे दिया, एक sprint में finished product की उम्मीद की, और कुछ ऐसा वापस पाया जो तकनीकी तौर पर चलता तो है लेकिन किसी भी input पर टूट जाता है जो happy path में न हो।
Loop प्रैक्टिस में कैसा दिखता है
आप tools को JSON schemas के तौर पर define करते हैं। Claude उन schemas को पढ़ता है, तय करता है कि उन्हें कब use करना है, structured arguments pass करता है, और आपका code असल logic को execute करता है। Claude कोड को कभी directly नहीं चलाता। वह पूछता है। आपका system काम करता है। फिर Claude को result मिलता है और वह आगे बढ़ता है।
यह अलगाव ज़्यादा important है जितना ज़्यादातर लोग समझते हैं। इसका मतलब है कि Claude हमेशा एक orchestrator है, executor नहीं। और यह framing हर architectural decision को shape करना चाहिए जो आप लेते हैं।
---
Tools design करना जिन्हें Claude असल में use कर सके
यहीं ज़्यादातर builds fail होते हैं। मैंने शायद पिछले साल दूसरे developers के 15 agent codebases को review किया है, और single most common problem न तो prompt engineering है और न ही model choice। यह badly designed tools हैं।
"badly designed" का प्रैक्टिस में क्या मतलब है:
- एक tool जिसका नाम
process_dataहै और जो आप किन parameters को pass करते हैं, इस पर निर्भर करते हुए पाँच unrelated चीज़ें करता है - Tool descriptions जो internal code comments की तरह पढ़े जाएँ ("calls the v2 endpoint with auth headers")
- Parameters जिनका नाम
typeयाmodeहो जो arbitrary strings के बजाय enums accept करें - Return value में कोई error information नहीं, इसलिए Claude को कोई idea नहीं कि call succeed हुई या नहीं
शुरुआती 2023 में, Seahawk के पास एक content pipeline project था जहाँ हमने एक manage_content tool बनाया था जो एक action parameter स्वीकार करता था: create, update, delete, publish, unpublish, archive। Claude गलत action चुनता रहता था क्योंकि schema से अकेले ये अंतर स्पष्ट नहीं थे। हमने इसे छह अलग-अलग tools में बाँट दिया। उस specific निर्णय पर accuracy हमारे internal evals में लगभग 60% से 94% हो गई। एक बदलाव।
जो नियम मैं अब Follow करता हूँ
- एक tool, एक काम। अगर आप tool के purpose को एक ही sentence में "और" के बिना describe नहीं कर सकते, तो इसे बाँट दीजिए।
- जहाँ भी संभव हो enums का इस्तेमाल कीजिए। Claude को strings guess करने न दीजिए।
- Claude के लिए description लिखिए, human developer के लिए नहीं। Claude को आपका codebase नहीं पता। उसे वही पता है जो आप बताएँ।
- हमेशा structured data return कीजिए जिसमें एक explicit success/failure field हो। Claude को silence से infer करने न दीजिए।
- Tool names को verb-first रखिए। search_orders, create_draft, fetch_customer_record। orders, draft,
customerनहीं।
Anthropic का tool use documentation schema structure पर गहराई से जाता है और सावधानी से पढ़ने योग्य है, sirf skim करने के लिए नहीं।
---
Context Management Hidden Cost है
यहाँ कुछ ऐसा है जिस पर कोई काफ़ी बात नहीं करता। Tokens मुफ़्त नहीं हैं, और agents भूखे हैं।
Loop में हर turn में पूरा conversation history, सभी tool schemas, system prompt, और tool results शामिल होते हैं। दस tools और एक detailed system prompt वाला एक moderately complex agent हर user session को 3,000-4,000 tokens से शुरू कर सकता है इससे पहले कि user ने एक भी character type किया हो। पाँच या छह tool calls with results add करिए, और आप एक resolved task के लिए 15,000-20,000 tokens देख रहे हैं। Claude की वर्तमान API pricing पर, ये किसी भी volume पर जल्दी जमा हो जाता है।
मैं इसे अब obsessively track करता हूँ। हर agent जो मैं ship करता हूँ, मैं QA के दौरान एक cost-per-resolution number run करता हूँ। अगर ये एक threshold से ऊपर है जिससे मैंने client के साथ पहले से agree किया है, तो मैं वापस जाता हूँ और system prompt को tighten करता हूँ, tool schemas को कम करता हूँ, या देखता हूँ कि क्या मैं prompt caching का इस्तेमाल करके static context को cache कर सकता हूँ, जो Anthropic ने add किया है और जिसे मैं genuinely हर project पर use करता हूँ। Cache-eligible tokens एक cache hit पर standard input rate का लगभग 10% cost करते हैं। एक busy agent पर जो एक ही system prompt को हर दिन हज़ारों बार rerun करता है, ये कोई rounding error नहीं है।
बिना चीज़ों को तोड़े Trimming करना
लालच हर edge case को cover करने वाला एक rich, detailed system prompt लिखने की है। इससे resist कीजिए। हर line जो आप add करते हैं वो हर turn पर tokens cost करती है। Common case के लिए लिखिए। Edge cases को tool return values में या shorter in-context instructions में handle कीजिए जो सही समय पर inject किए जाएँ।
मैं एक बार agent काम करने लगे तो tool descriptions को ruthlessly cut करता हूँ। अगर एक description कहता है "यह tool order database को search करता है और query से matching orders की एक list return करता है, जिसमें order ID, customer name, line items, shipping status, और timestamps शामिल हैं" तो मैं इसे "Orders को query string से search कीजिए। Matching order records return करता है।" में trim कर दूँगा। Claude काफ़ी smart है। उसे tool description में field list की जरूरत नहीं है अगर return schema properly उन fields को document करता है।
---
Multi-Agent Orchestration: जब एक Agent काफ़ी नहीं है
Single-agent systems एक specific complexity ceiling पर break होते हैं। मैंने वह ceiling पिछली spring में एक property management company के लिए एक project पर hit की। Agent को maintenance requests handle करने थे, contractors के साथ communicate करना था, एक Notion database को update करना था, SendGrid के through templated emails भेजने थे, और एक custom-built calendar API से availability data pull करने था। सात tools, जिनमें से कई के sub-workflows थे।
एक agent जो सभी का coordinate करने की कोशिश कर रहा हो unreliable बन गया। Context messy हो गया। Claude बीच में occasionally track खो देता था कि वो किस sub-task पर काम कर रहा है।
Fix retrospect में obvious था: orchestrator plus specialists। एक top-level Claude agent intent classification और routing handle करता है। Specialist sub-agents specific domains (communication, scheduling, data updates) को handle करते हैं और structured results report back करते हैं। Orchestrator को कभी नहीं पता कि हर specialist ने क्या किया। उसे बस output दिखता है।
यह pattern Anthropic के अपने multi-agent guidance में describe है और ये closely map करता है कि आप एक human team को कैसे design करेंगे। एक project manager व्यक्तिगत रूप से हर email नहीं लिखता और हर spreadsheet को update नहीं करता। वो delegate करता है, confirmation के लिए wait करता है, और आगे बढ़ता है।
Sub-Agent Design पर Practical Notes
- हर sub-agent को एक tight, specific system prompt दीजिए। कोई cross-domain instructions नहीं।
- सब-एजेंट्स को कभी भी अपने डोमेन से ज्यादा टूल्स नहीं रखने चाहिए। टूल ब्लोट मुख्य ऑर्केस्ट्रेटर में जितना खतरनाक है, सब-एजेंट्स में भी उतना ही है।
- कॉन्टेक्स्ट को स्पष्ट रूप से भेजें। यह मत मानें कि सब-एजेंट को पता है कि अपस्ट्रीम में क्या हुआ। उसे ठीक वही भेजें जो उसे चाहिए, कुछ और नहीं।
---
विफलताओं को सुंदरता से संभालना (क्योंकि वे होंगी)
प्रोडक्शन एजेंट्स विफल होते हैं। वे टाइम आउट होते हैं। बाहरी APIs 500 रिटर्न करते हैं। यूजर्स ऐसे इनपुट्स भेजते हैं जिनकी आपने कभी उम्मीद नहीं की। Claude कभी-कभी एक टूल स्कीमा को गलत तरीके से पढ़ता है और एक खराब आर्गुमेंट पास करता है।
सवाल यह नहीं है कि आपका एजेंट विफल होगा। सवाल यह है कि क्या यह सुरक्षित रूप से विफल होता है।
अब मैं हर एजेंट में बिना किसी अपवाद के तीन चीजें शामिल करता हूं:
- सभी बाहरी टूल कॉल्स पर बैकऑफ के साथ रिट्राई लॉजिक। सिर्फ रेट लिमिट एरर्स पर नहीं। किसी भी गैर-200 चीज़ पर।
- एक फॉलबैक पाथ जब एजेंट ने टास्क को रिज़ॉल्व किए बिना N से ज्यादा टूल कॉल्स कर दी हों। N अलग-अलग होता है, लेकिन मैं इसे आठ से ऊपर नहीं जाने देता। इस बिंदु पर कुछ गलत है और एक इंसान को शामिल होना चाहिए।
- सिस्टम प्रॉम्प्ट में स्पष्ट अनिश्चितता हैंडलिंग। मैं Claude को बताता हूं: अगर आपके पास कार्य को आत्मविश्वास से करने के लिए पर्याप्त जानकारी नहीं है, तो मान्यताओं पर आगे बढ़ने के बजाय एक स्पष्टीकरण प्रश्न पूछें।
तीसरी वाली ने मेरे द्वारा शुरुआत में जिक्र किए गए टिकट-ट्रिएज एजेंट को बचाया। पुनर्निर्मित संस्करण अब जब अनिश्चित होता है तो एक स्पष्टीकरण प्रश्न पूछता है। यूजर्स को कोई आपत्ति नहीं है। उनके टिकट को गलत कतार में जाने की बजाय एक प्रश्न का उत्तर देना बेहतर है।
---
Evals: आप इनके बिना शिप नहीं कर सकते
मैंने सपोर्ट टिकट एजेंट के पहले संस्करण पर सही तरीके से evals नहीं चलाए। वह वास्तव में गलती थी। बाकी सब कुछ उसका लक्षण था।
Evals को फैंसी होने की जरूरत नहीं है। जो मैं अब करता हूं वह निर्माण शुरू करने से पहले 40-60 प्रतिनिधि इनपुट्स का एक सेट बनाता हूं, जिसमें सामान्य केस, एज केसेज और विरोधी इनपुट्स शामिल हैं। मैं हर महत्वपूर्ण परिवर्तन के बाद सभी के विरुद्ध एजेंट चलाता हूं। मैं तीन संख्याएं ट्रैक करता हूं: टास्क कम्पलीशन रेट, टूल कॉल एक्यूरेसी (क्या इसने सही टूल को सही आर्गुमेंट्स के साथ कॉल किया), और हैलुसिनेशन रेट (क्या इसने कुछ ऐसा मना किया जो टूल रिजल्ट्स में आधारित नहीं था)।
एक प्रोडक्शन एजेंट के लिए, मैं 88% टास्क कम्पलीशन से नीचे शिप नहीं करूंगा और कस्टमर-फेसिंग मैसेजेस जैसी हाई-स्टेक्स आउटपुट्स में हैलुसिनेशन के लिए जीरो टॉलरेंस जहां विशिष्ट दावे हों (तारीखें, कीमतें, पॉलिसीज)।
Stanford से HELM बेंचमार्किंग फ्रेमवर्क eval डिज़ाइन के लिए प्रेरणा के लिए देखने योग्य है, भले ही आप अकादमिक स्केल पर न चल रहे हों। जिन केटेगरीज को वे टेस्ट करते हैं वे असली प्रोडक्शन रिक्वायरमेंट्स के साथ अच्छी तरह मैप करती हैं।
---
सिस्टम प्रॉम्प्ट लोड-बेयरिंग है
मैंने इस पिछले साल अपना विचार बदल दिया है। मैं सिस्टम प्रॉम्प्ट को सेटअप टेक्स्ट के रूप में ट्रीट करता था, कुछ ऐसा जो आप एक बार लिखते हैं और भूल जाते हैं। अब मैं इसे प्रोजेक्ट में सबसे महत्वपूर्ण फाइल के रूप में ट्रीट करता हूं।
एक अच्छी तरह से लिखी गई सिस्टम प्रॉम्प्ट चार चीजें करती है:
- एजेंट की पहचान और स्कोप को स्पष्ट रूप से परिभाषित करता है (यह क्या करता है और, गंभीर रूप से, यह स्पष्ट रूप से क्या नहीं करता है)
- टोन और आउटपुट फॉर्मेट की अपेक्षाएं सेट करता है
- सबसे सामान्य विफलता मोड्स को सक्रिय रूप से संभालता है ("अगर आप एक ऑर्डर नहीं खोज पाते हैं, तो स्पष्ट रूप से कहें बजाय अनुमान लगाने के")
- एस्केलेशन मानदंड स्थापित करता है
स्कोप डेफिनिशन वह है जिसे अधिकतर डेवलपर्स छोड़ते हैं। इसके बिना, Claude आपके इच्छा के तरीकों से सहायक होने का प्रयास करेगा। प्रॉपर्टी मैनेजमेंट एजेंट पर, पहली सिस्टम प्रॉम्प्ट ने स्पष्ट रूप से वित्तीय सलाह को बाहर नहीं निकाला। एक टेनेंट ने एजेंट से पूछा कि क्या उन्हें एक चार्ज पर विरोध करना चाहिए। Claude सहायक रूप से वजन दिया। यह नहीं है जो क्लाइंट ने भुगतान किया, और यह नहीं है जो एजेंट बनाया गया था।
एक वाक्य ने इसे ठीक किया: "आप वित्तीय विवादों, कानूनी मामलों, या पट्टे की व्याख्या पर सलाह देने के लिए अधिकृत नहीं हैं। इन विषयों के लिए यूजर्स को सीधे कार्यालय से संपर्क करने के लिए निर्देशित करें।"
हर उस डोमेन के लिए वह वाक्य लिखें जो स्कोप से बाहर है। यह न मानें कि Claude सीमाएँ स्वयं समझ लेगा।
---
FAQ
Claude Agent SDK सीधे Claude API का उपयोग करने से कैसे अलग है?
API आपको एक single request-response देता है। Agent SDK (और Anthropic द्वारा दस्तावेज़ित agent patterns) आपको एक structured loop देता है जहाँ Claude कई निर्णय ले सकता है, tools को कॉल कर सकता है, नतीजे प्राप्त कर सकता है, और turns के across reasoning जारी रख सकता है। यह एक विशिष्ट software package के बारे में कम है और एक pattern के बारे में अधिक है: tool definitions, multi-turn context management, और orchestration logic। आप उस loop को सक्षम करने के लिए API के चारों ओर scaffolding बना रहे हैं।
production-ready agent को ship करने के लिए realistic timeline क्या है?
ईमानदारी से कहूँ तो, किसी भी non-trivial चीज़ के लिए चार से छह हफ्ते। इनमें से दो हफ्ते tools को build और wire करने में लगते हैं। एक हफ्ता prompt engineering और iteration में। एक से दो हफ्ते evals, edge case handling, और QA में। जो कोई भी आपको एक हफ्ते में production agent देने का वादा करता है, वह या तो पहले कभी ship नहीं किया है या फिर आपको एक demo दे रहा है जिसे product के रूप में सजाया गया है।
क्या मुझे multi-agent system में सभी sub-agents के लिए Claude का उपयोग करना चाहिए, या models को मिक्स करना चाहिए?
मैं Claude का उपयोग उन सभी जगहों पर करता हूँ जहाँ nuanced reasoning की ज़रूरत होती है या जहाँ output quality end user को मायने रखती है। Simple classification tasks या high-volume low-stakes routing के लिए, एक छोटा और सस्ता model काम कर सकता है। लेकिन models को मिक्स करने से integration overhead बढ़ता है और debugging कठिन हो जाती है। सब कुछ के लिए Claude से शुरुआत करें, फिर real production data दिखने के बाद optimize करें कि कहाँ एक lighter model काफ़ी है।
मैं एक agent को off-script जाने से कैसे रोकूँ?
तीन चीज़ें एक साथ काम करती हैं: explicit out-of-scope statements के साथ tight system prompt, tool design जो physically निश्चित actions को रोकता है (agent को ऐसा tool न दें जिसका उपयोग उसे नहीं करना चाहिए), और customer-facing किसी भी चीज़ पर output validation। आप सिर्फ़ system prompt पर निर्भर नहीं रह सकते। Defence in depth।
developers agent memory के साथ सबसे बड़ी गलती क्या करते हैं?
context window को infinite मानना। यह infinite नहीं है। मैंने जो poorly built agents में failures देखी हैं, वह ज़्यादातर उस context से आती हैं जो irrelevant history से bloated हो गया है, जिससे Claude को noise के through reasoning करनी पड़ती है। Aggressively prune करें। जहाँ हो सके summarise करें। केवल वही आगे बढ़ाएँ जिसकी agent को current task complete करने के लिए सच में ज़रूरत है।
---
ईमानदार summary यह है: SDK कठिन हिस्सा नहीं है। कठिन हिस्सा वही है जो software में हमेशा रहा है – scope के बारे में स्पष्ट सोच, failure के लिए design, और shipping से पहले testing। Claude एक remarkably capable reasoning layer है, लेकिन यह इसके चारों ओर badly designed system की भरपाई नहीं कर सकता। पहले plumbing ठीक से लगाएँ।