प्रोडक्शन में AI एजेंट को डीबग कैसे करें (एक फील्ड गाइड)

विषय-सूची

जून 2026 में अपडेटेड।

TL;DR: प्रोडक्शन AI एजेंट को डीबग करना ज़्यादातर यह पहचानने के बारे में है कि कौन-सी लेयर फेल हुई — प्रॉम्प्ट, टूल कॉल, मॉडल आउटपुट, या ऑर्केस्ट्रेशन। मैं हर स्टेप को एक ट्रेस ID के साथ लॉग करता हूँ, बिल्कुल वही इनपुट रिप्ले करता हूँ, और वहीं से बाइसेक्ट करता हूँ। मेरे एजेंट्स में, जो “AI बग” जैसा दिखता है उसका करीब 70% प्लंबिंग निकलता है: एक खराब फ़ॉर्मेट वाला टूल रिज़ल्ट, एक कटा हुआ इनपुट, एक चुपचाप निगल लिया गया एक्सेप्शन।

ऑपरेटर की नज़र: मैं 100 से ज़्यादा प्रोडक्शन एजेंट चलाता हूँ — Pickleland के लिए बुकिंग फ्लो, कंटेंट पाइपलाइन, इनबॉक्स ट्रायाजर। वे वैसे ही टूटते हैं जैसे हर सॉफ़्टवेयर टूटता है, साथ में कुछ नए तरीकों से भी। यह वही फील्ड गाइड है जो काश मेरे पास होती: टोकन की दीवार को घूरे बिना गड़बड़ करने वाली लेयर को कैसे ढूँढें।

जब कोई एजेंट प्रोडक्शन में गलत व्यवहार करता है, तो प्रवृत्ति होती है मॉडल को दोष देने की। “Claude ने हैल्युसिनेट किया।” कभी-कभी सच। आमतौर पर नहीं। मॉडल पाँच या छह की स्टैक में एक लेयर है, और बग कहीं ज़्यादा बार उस लेयर में होता है जो आपने लिखी, बजाय उसके जो Anthropic ने भेजी। यह पोस्ट वह व्यवस्थित तरीका है जिससे मैं इसे ढूँढता हूँ।

कुछ भी डीबग करने से पहले हर रन को ट्रेस करने योग्य बनाएँ

जो आप देख नहीं सकते, उसे आप डीबग नहीं कर सकते। सबसे ज़्यादा लाभ देने वाली चीज़ जो आप कर सकते हैं — किसी भी खास बग के सामने आने से पहले — वह है हर एजेंट रन में एक ट्रेस ID जोड़ना और उसके उठाए गए हर स्टेप को लॉग करना।

एक “स्टेप” वह सब कुछ है जो किसी सीमा को पार करता है: आने वाला ट्रिगर, हर मॉडल कॉल (पूरे मैसेज ऐरे के साथ), हर टूल कॉल (आर्गुमेंट्स के साथ), हर टूल रिज़ल्ट, और अंतिम आउटपुट। इन्हें ट्रेस ID से कीड स्ट्रक्चर्ड JSON के रूप में लॉग करें।

function logStep(traceId: string, step: string, payload: unknown) {
  console.log(JSON.stringify({
    traceId,
    step,            // "trigger" | "model_call" | "tool_call" | "tool_result" | "output"
    ts: Date.now(),
    payload,
  }));
}

Cloudflare Workers पर मैं इन्हें एक क्यू में और एक टेबल में भेजता हूँ; लोकल में ये stdout पर जाते हैं। नियम अटल है: अगर कोई स्टेप लॉग नहीं हुआ, तो डीबगिंग की दृष्टि से वह हुआ ही नहीं। यह उस इंस्ट्रुमेंटेशन को दर्शाता है जिसका वर्णन मैं जिस एजेंट स्टैक का मैं इस्तेमाल करता हूँ में करता हूँ — ट्रेस ID वह रीढ़ है जिस पर बाकी सब कुछ टँगा होता है।

लेयर को अलग करें: प्रॉम्प्ट, टूल, मॉडल, या ऑर्केस्ट्रेशन

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

1. इनपुट लेयर (सबसे आम दोषी)

फेल हुई मॉडल कॉल में गया हुआ बिल्कुल वही messages ऐरे निकालें। पुनर्निर्माण नहीं — लॉग से अक्षरशः पेलोड। फिर इसे ऐसे पढ़ें जैसे कोई अजनबी पढ़ता। मेरे “मॉडल ने निर्देश नज़रअंदाज़ किए” वाले आधे बग दरअसल ये होते हैं:

• एक टूल रिज़ल्ट जो "[object Object]" के रूप में वापस आया क्योंकि कुछ गलत तरीके से स्ट्रिंगिफ़ाई हो गया।
• एक इनपुट जो वाक्य के बीच में कट गया क्योंकि उसने कॉन्टेक्स्ट विंडो को फोड़ दिया और एक भोली स्लाइस ने उसे काट दिया।
• एक वैरिएबल जो undefined के रूप में इंटरपोलेट हुआ और चुपचाप प्रॉम्प्ट को ज़हरीला कर गया।

अगर इनपुट गलत है, तो मॉडल ने कचरे पर अपना काम बखूबी किया। प्लंबिंग ठीक करें।

2. टूल लेयर

अगर इनपुट साफ़ दिखता है, तो जाँचें कि कहीं किसी टूल ने ऐसी कोई एरर तो नहीं लौटाई जिसे एजेंट ने सफलता मान लिया। एक क्लासिक: एक API { "error": "rate limited" } बॉडी के साथ 200 लौटाती है, आपका टूल रैपर बॉडी की जाँच नहीं करता, और एजेंट आत्मविश्वास से एक एरर मैसेज पर कार्रवाई कर देता है। टूल रिज़ल्ट को कच्चा लॉग करें और उनके आकार को असर्ट करें।

3. मॉडल लेयर

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

4. ऑर्केस्ट्रेशन लेयर

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

नॉन-डिटर्मिनिज़्म से लड़ने के बजाय उसे दोहराएँ

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

पहला, जो फिक्स कर सकते हैं, करें। डीबग करते समय temperature: 0 सेट करें। यह Claude को पूरी तरह डिटर्मिनिस्टिक नहीं बनाएगा, पर वैरिएंस को इतना तेज़ी से संकरा कर देता है कि आप असली बग को सैंपलिंग नॉइज़ से अलग बता सकें।

दूसरा, इसे N बार चलाएँ। अगर कोई फ़ेल्योर हर 20 रन में 1 बार दोहराता है, तो बिल्कुल वही इनपुट 50 बार लूप करें और हर आउटपुट कैप्चर करें। अब आपके पास एक सैंपल है, एक किस्सा नहीं। एक बग जो 5% बार चलता है, वह असली बग है — आपको उसे देखने के लिए बस वॉल्यूम चाहिए।

for i in $(seq 1 50); do
  node replay.mjs --trace=abc123 >> runs.jsonl
done
# फिर फ़ेल्योर गिनें
grep -c '"status":"fail"' runs.jsonl

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

एक रिप्ले हार्नेस बनाएँ ताकि आप प्रोडक्शन में डीबग करना बंद कर दें

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

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

एक अच्छा रिप्ले हार्नेस आपको म्यूटेट और री-रन करने भी देता है: सिस्टम प्रॉम्प्ट की एक लाइन बदलें, वही 50 फेल हुए ट्रेस रिप्ले करें, और देखें कि अब कितने पास होते हैं। यही डीबगिंग से eval तक का पुल है — एक बार आपके पास फेल हुए ट्रेस का एक कॉर्पस हो, तो आपके पास एक रिग्रेशन सूट की शुरुआत है।

उन मेट्रिक्स पर नज़र रखें जो वाकई टूटने की भविष्यवाणी करते हैं

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

• टूल-कॉल सक्सेस रेट प्रति टूल। यहाँ गिरावट अक्सर एक दिखाई देने वाली फ़ेल्योर से पहले आती है।
• आउटपुट स्कीमा वैलिडिटी — कितने % आउटपुट अपेक्षित स्ट्रक्चर के विरुद्ध पार्स होते हैं। मैं हर आउटपुट को Zod से वैलिडेट करता हूँ और जब वैलिडिटी गिरती है तो अलर्ट देता हूँ।
• लूप लंबाई — प्रति रन स्टेप्स की औसत संख्या। अचानक स्पाइक आमतौर पर मतलब होता है कि एजेंट रीट्राई में फँस गया है।
• प्रति रन लागत — एक बेकाबू लूप शिकायत के रूप में दिखने से पहले लागत स्पाइक के रूप में दिखता है। (जब लागत मायने रखती है, तो Haiku बनाम Sonnet का गणित जानने लायक है।)

मैं इन्हें वैसे ही ट्रैक करता हूँ जैसे बाकी सब कुछ — देखें मैं कैसे मापता हूँ कि कोई AI एजेंट वाकई काम कर रहा है या नहीं। एक मूक फ़ेल्योर को पकड़ने वाला मेट्रिक, शोरगुल वाली फ़ेल्योर पकड़ने वाले दस मेट्रिक्स के बराबर है।

5-मिनट का ट्राएज चेकलिस्ट

जब कोई एजेंट टूटता है और मैं समय की दौड़ में होता हूँ, तो मैं यह क्रम में चलाता हूँ:

1. फेल हुए रन का ट्रेस ID हासिल करें।
2. फेल हुए स्टेप का बिल्कुल वही इनपुट पढ़ें। क्या यह सुगठित है? (यहाँ ~50% मामले हल हो जाते हैं।)
3. उस ट्रेस में टूल रिज़ल्ट्स की जाँच करें कि कहीं सफलता के भेस में कोई एरर तो नहीं।
4. temperature: 0 पर स्टेप को ऑफ़लाइन रिप्ले करें। क्या यह दोहराता है?
5. अगर दोहराता है, तो यह प्रॉम्प्ट/मॉडल का मसला है — ठीक करें और ट्रेस कॉर्पस फिर से चलाएँ। अगर नहीं, तो यह नॉन-डिटर्मिनिज़्म या कोई स्टेट/ऑर्केस्ट्रेशन बग है — इसे 50× लूप करके इसकी विशेषता पहचानें।

अनुशासित आइसोलेशन हर बार चतुर प्रॉम्प्टिंग को हरा देता है। मॉडल शायद ही कभी समस्या होता है; उसके इर्द-गिर्द का सिस्टम आमतौर पर होता है।

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

मैं ऐसे AI एजेंट को कैसे डीबग करूँ जो सिर्फ़ कभी-कभी फेल होता है?

एक लॉग किए हुए ट्रेस से बिल्कुल वही इनपुट कैप्चर करें और उसे टेम्परेचर 0 पर 50+ बार रिप्ले करें। रुक-रुक कर होने वाले फ़ेल्योर कम फायरिंग-रेट वाले असली बग हैं — वॉल्यूम किस्से को एक पुनरुत्पाद्य सैंपल में बदल देता है जिसे आप डिफ़ करके ठीक कर सकते हैं।

बग आमतौर पर मॉडल में होता है या मेरे कोड में?

मेरे प्रोडक्शन एजेंट्स में, दिखने वाले “AI बग” का करीब 70% प्लंबिंग होता है: खराब फ़ॉर्मेट वाले टूल रिज़ल्ट, कटे हुए इनपुट, निगले गए एक्सेप्शन, या स्टेप्स के बीच खोई हुई स्टेट। मॉडल पर शक करने से पहले इनपुट और टूल लेयर को खारिज करें।

एजेंट्स डीबग करने के लिए मुझे न्यूनतम कितनी लॉगिंग चाहिए?

हर रन पर एक ट्रेस ID, साथ ही ट्रिगर, हर मॉडल कॉल (पूरा मैसेज ऐरे), हर टूल कॉल और उसका कच्चा रिज़ल्ट, और अंतिम आउटपुट के स्ट्रक्चर्ड लॉग। अगर कोई स्टेप लॉग नहीं है, तो आप उसे डीबग नहीं कर सकते।

मैं लाइव प्रोडक्शन के विरुद्ध डीबग करना कैसे बंद करूँ?

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