AI एजेंट की observability: एजेंट ने क्या किया, यह कैसे समझें और क्या log करें

AI एजेंट की observability क्या है

AI एजेंट की observability का अर्थ है कि एजेंट की याद या उसके शब्दों पर नहीं, बल्कि artifacts के आधार पर तीन सवालों के जवाब मिल सकें: उसने क्या किया, वैसा क्यों किया और उसके परिणाम सही हैं, यह किससे साबित होता है। अगर बीस मिनट काम के बाद एजेंट कहता है «हो गया, पर दो टेस्ट गिर रहे हैं, शायद timing की वजह से», और यह पूछने पर कि कौन-से paths प्रभावित हुए, वह जवाब देता है «कोड दिखाइए» — तो observability नहीं है। एजेंट बेवकूफ़ नहीं है, बस उसके पास दिखाने को कुछ नहीं है।

यह समस्या व्यवस्थित है। वही एजेंट एक हफ़्ते में दस बार ईमानदारी से «हो गया» कह सकता है, और हर बार इसका मतलब अलग होगा: कहीं सारे टेस्ट चले, कहीं सिर्फ़ एक, कहीं कुछ नहीं। प्रोजेक्ट जितना पुराना होता है, हर अगला सत्र उतना महँगा होता है, क्योंकि वह खुदाई से शुरू होता है।

दो स्तर: runtime और प्रक्रिया

Observability को अक्सर logs के बराबर समझ लिया जाता है, पर logs आधा हिस्सा हैं।

केवल runtime: दिखता है कि क्या टूटा, पर पता नहीं चलता कि लक्ष्य क्या था। केवल प्रक्रिया: पता चलता है कि क्या चाहा गया था, पर दिखता नहीं कि कोशिश क्यों नाकाम हुई। दोनों चाहिए।

एजेंट यह खुद क्यों नहीं करेगा

एजेंट से «बेहतर log करो» कहने से तीन कारणों से काम नहीं चलता।

• उसे पता नहीं कि उसे क्या नहीं पता। जिस संकेत के महत्व का उसे अंदाज़ा नहीं, उसे वह log नहीं करेगा।
• फ़ॉर्मेट बदलता रहता है। एक सत्र में वह विस्तार से लिखता है, दूसरे में एक पंक्ति में। सत्रों की तुलना और आँकड़े निकालना असंभव हो जाता है।
• प्रक्रिया logs से बंद नहीं होती। «ऐसा क्यों किया» का जवाब उन दस्तावेज़ों में होता है जो काम से पहले बने, न कि कमांड के आउटपुट में।

इसलिए observability को harness में रखा जाता है, यानी एजेंट के वातावरण में: templates, hooks, scripts और अनिवार्य रिपोर्ट का फ़ॉर्मेट।

क्या log करें: न्यूनतम सेट

अच्छा लॉग हर बात की स्टेनोग्राफ़ी नहीं होता। वह तथ्यों का ऐसा सेट है जिससे काम का क्रम दोबारा बनाया जा सके और आँकड़े निकाले जा सकें।

• पहचानकर्ता: session id, कार्य या फ़ीचर का id, एजेंट का model।
• Side effects वाली कार्रवाइयाँ: कौन-सी कमांड चलीं, कौन-सी फ़ाइलें बदलीं। फ़ाइल पढ़ने को आम तौर पर लिखना ज़रूरी नहीं।
• जाँचों के परिणाम: कौन-सी जाँच चली, exit code क्या था, कितने टेस्ट पास हुए और कितने गिरे।
• Retries: किसी कदम पर कितने प्रयास हुए और वे एक-दूसरे से किस तरह अलग थे।
• खर्च: tokens और समय, अगर tool उन्हें देता है।
• नतीजा: कार्य स्वीकार हुआ, खारिज हुआ या छोड़ दिया गया, और क्यों।

क्या न लिखें: सीक्रेट्स, access tokens, और कमांड के आउटपुट से निजी डेटा। लॉग सार्वजनिक हो सकता है या फिर model के context में वापस जा सकता है।

Claude Code के hooks से कार्रवाई का लॉग

Claude Code में लॉग hooks से रखना सुविधाजनक है: ये ऐसी कमांड हैं जिन्हें tool खुद चलाता है, model नहीं, इसलिए ये हमेशा चलते हैं। Hook को इनपुट में event का JSON मिलता है, जिसमें session id, tool का नाम और उसके parameters होते हैं। .claude/settings.json में ऐसा सेटअप, जो Bash, Edit या Write के हर कॉल के बाद लॉग में एक पंक्ति जोड़ता है:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash|Edit|Write",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/log-action.sh" }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# .claude/hooks/log-action.sh — हर कार्रवाई के लिए JSON की एक पंक्ति
mkdir -p .agent/logs
jq -c '{ts: (now | todate), session: .session_id, tool: .tool_name,
        cmd: .tool_input.command, file: .tool_input.file_path}' \
  >> .agent/logs/actions.jsonl || true

JSONL फ़ॉर्मेट (हर पंक्ति में एक JSON रिकॉर्ड) इसलिए सुविधाजनक है कि इसे jq से आसानी से छाना जा सकता है और किसी भी विश्लेषण सिस्टम में डाला जा सकता है। इसके अलावा Claude Code पूरा सत्र-इतिहास स्थानीय रूप से ~/.claude/projects/ डायरेक्टरी में खुद रखता है — अगर तर्क और आउटपुट पूरे देखने हों तो वहाँ देखा जा सकता है, पर आँकड़ों के लिए अपना संक्षिप्त लॉग अधिक उपयोगी है।

Tracing: सत्र के लिए एक trace, कार्य के लिए एक span

जब एजेंट कई हों या शेड्यूल पर चलते हों, तो टेक्स्ट वाले लॉग काफ़ी नहीं होते: आँकड़े चाहिए। यहाँ distributed tracing के सामान्य tools और OpenTelemetry मानक काम आते हैं।

• Trace — एजेंट का एक सत्र।
• Span — सत्र के भीतर एक कार्य।
• भीतरी spans — सत्यापन के कदम: build, tests, e2e।

हर span पर कम से कम ये attributes रखें: फ़ीचर और session का id, model, जाँच का परिणाम, tokens और retries की संख्या। ऐसा डेटा Jaeger, Grafana Tempo या Honeycomb में पढ़ा जा सकता है और वे सवाल हल करता है जो एक सत्र में दिखते ही नहीं: किस प्रकार के कार्यों को अधिक retries चाहिए, एजेंट tokens कहाँ सबसे ज़्यादा खर्च करता है, और harness में किस बदलाव के बाद स्वीकृत कार्यों का अनुपात गिरा। Claude Code में OpenTelemetry के ज़रिए metrics और events निकालने की सुविधा है — यह environment variables से चालू होती है, विवरण tool के दस्तावेज़ में हैं।

Commits को लॉग की तरह

सबसे सस्ता और भरोसेमंद लॉग आपके पास पहले से है — git। बस उसे पढ़ने योग्य बनाना है।

1. एक commit — एक कार्य। तब git log किए गए काम की सूची जैसा दिखता है, और किसी कार्य को वापस लेना एक git revert है।
2. संदेश में — क्या बदला और कैसे जाँचा। «fix» नहीं, बल्कि «क्या बदला, क्यों, किस कमांड से जाँचा गया»।
3. हरी जाँच के बाद ही commit। तब इतिहास का हर बिंदु काम करती हालत है, और git bisect दोषी commit तक पहुँचा देता है।

fix(payments): छूट का राउंडिंग पूरे पैसों (कोपेक) तक

छूट float में गिनी जा रही थी, 999.99 पर एक कोपेक खो जाता था।
गणना int में, कोपेक में, कर दी गई।
जाँचा गया: make test (142 passed), make e2e checkout — ठीक।
Scope से बाहर: रिपोर्ट में राउंडिंग, BACKLOG.md में दर्ज।

एजेंट की रिपोर्ट: धारणाओं की जगह सबूत

एजेंट का आख़िरी संदेश भी observability का artifact है, अगर उसका रूप तय हो। Template को AGENTS.md या CLAUDE.md में लिखें:

## कार्य के अंत में रिपोर्ट
- क्या किया गया: बदलावों की सूची (फ़ाइल — सार)
- कैसे जाँचा: सटीक कमांड और उनका परिणाम
- क्या जाँचा नहीं गया और क्यों
- अनुबंध से विचलन
- इंसान के लिए खुले प्रश्न

मुख्य नियम: हर दावा सबूत से जुड़ा हो — फ़ाइल और पंक्ति, टेस्ट का आउटपुट, लॉग की प्रविष्टि। «ठीक दिख रहा है» और «मुझे लगता है, ठीक है» रिपोर्ट नहीं गिने जाते। «क्या नहीं जाँचा गया» वाला बिंदु विशेष रूप से कीमती है, क्योंकि वह ईमानदारी से बताता है कि भरोसे की सीमा कहाँ है।

कोड से पहले अनुबंध, बाद में rubric

प्रक्रिया वाला स्तर काम से पहले शुरू होता है। एक छोटा अनुबंध (sprint contract) scope, स्वीकृति मानदंड, «scope से बाहर» वाला हिस्सा और इंसान द्वारा तय होने वाले खुले प्रश्न तय करता है। «scope से बाहर» वाला हिस्सा परिणाम पर होने वाले आधे विवादों को पहले ही रोक देता है।

काम के बाद परिणाम को छाप के आधार पर नहीं, rubric से आँकें। वरना दो अनुभवी reviewers अलग-अलग फ़ैसले देंगे, और मूल्यांकन लॉटरी बन जाएगा।

हर आयाम को A/B/C/D मिलता है, और बिना सबूत वाला ग्रेड अमान्य है। निर्णय का सरल नियम: एक D या दो C — अस्वीकार, साथ में सूची कि क्या ठीक करना है। यही rubric कोई अलग जाँच-एजेंट भी लागू कर सकता है।

एक सत्र में एजेंट ने क्या किया, यह कैसे परखें

अगर रिपोर्ट नहीं है या उस पर भरोसा नहीं, तो artifacts को इस क्रम में देखें।

1. Working tree की स्थिति: git status — क्या बिना commit रह गया, कोई कचरा फ़ाइल तो नहीं।
2. इतिहास: सत्र की शुरुआत से git log --stat — कौन-से commits और फ़ाइलें।
3. बदलावों का पैमाना: git diff --stat main...HEAD, फिर महत्वपूर्ण फ़ाइलों का पूरा diff।
4. कार्रवाई का लॉग: कौन-सी कमांड चलीं और जाँचों ने क्या लौटाया।
5. दोबारा जाँच: build और टेस्ट खुद चलाएँ। कमांड के आउटपुट पर भरोसा करें, दोबारा सुनाए गए विवरण पर नहीं।

# आख़िरी सत्र में एजेंट ने कौन-सी कमांड चलाईं
jq -r 'select(.tool=="Bash") | .cmd' .agent/logs/actions.jsonl | tail -n 30
# कौन-सी फ़ाइलें सबसे ज़्यादा बदलीं
jq -r '.file // empty' .agent/logs/actions.jsonl | sort | uniq -c | sort -rn | head

आम गलतियाँ

• सब कुछ log करना। गीगाबाइट की स्टेनोग्राफ़ी कोई नहीं पढ़ता। Side effects वाली कार्रवाइयाँ और जाँचों के परिणाम लिखें।
• खुला फ़ॉर्मेट। अगर लॉग का फ़ॉर्मेट एजेंट खुद तय करता है, तो आँकड़े नहीं बनेंगे। फ़ॉर्मेट harness तय करे।
• बिना कमांड के आउटपुट वाली रिपोर्ट पर भरोसा। «टेस्ट हरे हैं» बिना आउटपुट के केवल राय है।
• अंधाधुंध retries। विफलता का कारण जाने बिना एजेंट यहाँ-वहाँ बदलाव करता है। पहले निदान माँगें, जो लॉग के लिंक के साथ हो, फिर सुधार।
• «बाद में हटा देंगे»। Debug की फ़ाइलें और बिना commit के बदलाव अगले सत्र को उलझा देते हैं: वह अस्थायी और जानबूझकर किए गए बदलाव में फ़र्क नहीं कर पाता।

निष्कर्ष

AI एजेंट की observability दो स्तरों से बनती है: runtime (hooks से कार्रवाई का लॉग, traces, जाँचों के विवरण वाले commits) और प्रक्रिया (काम से पहले अनुबंध, rubric और सबूत के लिंक वाली रिपोर्ट)। तब «हो गया» हर सत्र में एक ही अर्थ रखता है, और एजेंट के काम का विश्लेषण मिनटों में हो जाता है। यह विषय हम harness engineering के कोर्स में एक असली भुगतान-backend प्रोजेक्ट पर व्यावहारिक रूप से समझाते हैं।