ऐसी agent tool errors जो secrets उजागर किए बिना मदद करें

एजेंट टूल की त्रुटियों में एजेंट को संभलने के लिए पर्याप्त संरचना होनी चाहिए, लेकिन हर विफल अनुरोध को क्रेडेंशियल निर्यात में नहीं बदलना चाहिए। इस सीमा को समझाना आसान है और व्यवहार में इसका उल्लंघन अक्सर होता है: कोई wrapper exception पकड़ता है, library message लौटा देता है और चुपचाप मॉडल को URL, Authorization header, certificate subject, SSH target या token का टुकड़ा दे देता है।

मैंने अच्छी नीयत से जोड़े गए debugging field से नुकसान शुरू होते देखा है। एजेंट को लगातार 401 responses मिल रहे थे, इसलिए किसी ने request_headers जोड़ दिया। एजेंट ने error को अपने working notes में कॉपी कर लिया। फिर वे notes pull request में चिपकाए गए, support system को भेजे गए या evaluation trace में रखे गए। मूल विफलता बीत गई। Secret वहीं रह गया।

सही डिज़ाइन एजेंट को यह सीमित जानकारी देता है कि क्या हुआ, वह सुरक्षित रूप से आगे क्या कर सकता है और मानव ऑपरेटर के लिए correlation handle क्या है। कच्चे सबूत को action boundary के पीछे रखा जाता है। यह उपयोगी errors और secret-safe errors में से किसी एक को चुनने का सवाल नहीं है। यह interface design का काम है।

Error response भी security boundary का हिस्सा है

एजेंट tool output को working memory की तरह इस्तेमाल करता है। वह output को उपयोगकर्ता के सामने उद्धृत कर सकता है, किसी फ़ाइल में रख सकता है, दूसरे टूल को भेज सकता है या उसके आधार पर retry चुन सकता है। इसलिए action gateway से लौटने वाले हर field को किसी untrusted caller के सामने disclosure मानना चाहिए, भले ही caller उस developer द्वारा चलाया गया एजेंट हो जो मशीन का मालिक है।

एक tool call के दो audience होते हैं। एजेंट को operational facts चाहिए: क्या कार्रवाई चली, क्या वह retry कर सकता है, क्या consent चाहिए और कौन-सा input बदलना है? ऑपरेटर को forensic facts चाहिए: कौन-सा credential चुना गया, कौन-सा exact route बुलाया गया, कौन-सा DNS resolver विफल हुआ और remote peer ने क्या कहा। दूसरे audience की जरूरत पूरी करने के लिए उसका evidence पहले audience को न दें।

यह अंतर तब सबसे महत्वपूर्ण होता है जब एजेंट बार-बार टूल चला सकता है। verbose error को एक बार देखने वाला इंसान शायद उसमें bearer token पहचान ले। एजेंट उसे दर्जनों turns तक बचाकर रख सकता है और फिर generated code या test fixture में डाल सकता है। ऐसा होने के लिए मॉडल का दुर्भावनापूर्ण होना जरूरी नहीं है।

Interface को इस स्पष्ट नियम पर बनाएं: caller को केवल वही fields मिलें जो public issue में कॉपी किए जाने पर भी सुरक्षित रहें। जो field इस परीक्षण में विफल हो, उसे protected diagnostics में रखें या छोड़ दें।

एजेंट को exception strings नहीं, फैसले दें

उपयोगी response एजेंट को बताता है कि उसके सामने किस तरह का फैसला है। Raw exceptions न तो यह काम भरोसेमंद ढंग से करते हैं, न सुरक्षित ढंग से। उनका wording operating system releases और client library versions के साथ बदलता है। वे अक्सर technical cause को ऐसी सामग्री के साथ मिला देते हैं जिसे निजी रहना चाहिए।

Codes की छोटी, documented vocabulary इस्तेमाल करें। हर code को caller के किसी खास व्यवहार से जोड़ें। Codes इतने बारीक न बनाएं कि हर संभावित upstream failure को फिर से लिखना पड़े।

एक व्यावहारिक response shape इस तरह दिख सकता है:

{
  "ok": false,
  "code": "AUTH_FAILED",
  "message": "The remote service rejected the stored credential.",
  "action": "stop_and_report",
  "retryable": false,
  "request_id": "act_7f3c2a91",
  "http_status": 401
}

एजेंट रुक सकता है, उपयोगकर्ता को बता सकता है कि authentication पर ध्यान चाहिए और request ID शामिल कर सकता है। यह फैसला लेने के लिए उसे bearer token, authorization scheme, account email या copied response body की जरूरत नहीं है।

action केवल एक अस्पष्ट boolean से अधिक उपयोगी है। Boolean बताता है कि समय बीतने से समस्या ठीक हो सकती है या नहीं। Action एजेंट को बताता है कि उसे करना क्या चाहिए। Allowed values सीमित रखें:

• retry_after_delay अस्थायी और सुरक्षित रूप से दोहराए जा सकने वाले operations के लिए।
• repair_input ऐसे request के लिए जिसे एजेंट नई authority के बिना सुधार सकता है।
• request_approval तब, जब किसी व्यक्ति को कार्रवाई की अनुमति देनी हो।
• stop_and_report उन failures के लिए जिन पर operator का काम जरूरी है।
• inspect_outcome तब, जब write remote service तक पहुंच गया हो सकता है।

आखिरी value को विशेष महत्व दें। Write भेजने के बाद आया timeout, भेजने से पहले आए timeout जैसा नहीं है। दोनों को NETWORK_ERROR में मिला देने पर एजेंट संभवतः पूरी हो चुकी कार्रवाई दोहराएगा। इसी से duplicate tickets, deployments, records और destructive commands बनते हैं।

http_status तभी expose करें जब वह meaningful और safe हो। HTTP calls में यह अक्सर उपयोगी संदर्भ है, लेकिन इसे पूरा उत्तर न समझें। 403 upstream authorization failure, resource-level restriction या gateway decision, कुछ भी हो सकता है। आपके tool code को वह behavior स्पष्ट करना चाहिए जो एजेंट को अपनाना है।

Stable code taxonomy को इतना छोटा रखें कि उसका परीक्षण हो सके

Code taxonomy को network stack की हर layer नहीं, ownership और recovery का वर्णन करना चाहिए। अगर पहले हफ्ते के बाद आपकी सूची में पचास codes हो गए हैं, तो शायद आप implementation details को किसी और नाम से export कर रहे हैं।

ऐसी categories से शुरुआत करें जिनसे caller अलग action ले सके:

Primary contract के रूप में ERROR, FAILED या EXCEPTION इस्तेमाल न करें। ऐसे labels interpretation का बोझ एजेंट पर डालते हैं, जो prose से remedy का अनुमान लगाएगा। अनुमान गलत हो सकता है।

Code के अर्थ स्थिर रखें। आप human message सुधार सकते हैं, retry_after_seconds field जोड़ सकते हैं या कोई नया safe status value शामिल कर सकते हैं। AUTH_FAILED का अर्थ bad credentials और local approval refusal दोनों न बनाएं। एजेंट और उसके आसपास का orchestration अंततः इस पर branch करेगा।

RFC 9457, «Problem Details for HTTP APIs», एक उपयोगी आधार देता है: response में stable problem type, title, status, detail और instance reference हो सकते हैं। इसकी वह चेतावनी महत्वपूर्ण है जिसे teams छोड़ देती हैं। RFC कहता है कि detail समस्या सुधारने में मदद करे और problem details sensitive information उजागर कर सकते हैं। Agent tools के लिए stable type या code को contract बनाएं, detail छोटा रखें और instance या request ID के माध्यम से operator को protected evidence तक पहुंच दें।

Request headers और connection errors context नहीं, evidence हैं

Teams अक्सर raw headers और transport messages को «context» कहती हैं। वे evidence हैं। Evidence access controls वाले audit record में होना चाहिए, agent response में नहीं।

एक विफल API request पर विचार करें। Typical HTTP library exception में पूरा requested URL, redirect location, proxy address, response headers और response body का कुछ हिस्सा शामिल हो सकता है। इनमें से कोई भी secret ले जा सकता है। पुराने APIs में query parameters अब भी API keys रखते हैं। Location headers में अक्सर signed download URLs होते हैं। Cookies और custom authentication headers स्पष्ट leaks हैं। कम स्पष्ट fields, जैसे X-Request-Id, ठीक हो सकते हैं, जबकि X-Forwarded-Host या internal service header ऐसी infrastructure जानकारी दिखा सकते हैं जिसकी एजेंट को कोई जरूरत नहीं थी।

SSH errors में भी यही अनुशासन चाहिए। Private target वाली command line, known-hosts path, offered identity file या raw host-key mismatch text न लौटाएं। Host-key mismatch का caller-relevant अर्थ है: remote identity verify न हो पाने के कारण connection block है। वही अर्थ लौटाएं। Fingerprint comparison, paths और library diagnostics operator के लिए बचाकर रखें।

OAuth 2.0 इस बात को खास तौर पर स्पष्ट करता है। RFC 6750 कहता है कि bearer token जिस व्यक्ति के पास हो, उसे access दे सकता है और clients को storage और transport में tokens को disclosure से बचाना चाहिए। ऐसा error handler जो bearer token को trace में कॉपी कर देता है, इस requirement को विफल कर देता है, भले ही मूल request ने TLS का सही इस्तेमाल किया हो।

Logs में फैलने के बाद नहीं, serialization से पहले sanitize करें। General log sink पर redaction filter backstop के रूप में उपयोगी है, लेकिन वही boundary नहीं है। तब तक thrown exception tool result, telemetry event या crash report से जुड़ चुका हो सकता है।

Agent तक जाने वाले fields के लिए allowlist इस्तेमाल करें। Denylist आखिरकार x-api-token, signed query parameter, vendor-specific session field या नई library property को छोड़ देगी। Allowlist disclosure से शुरू ही नहीं होती और केवल पहचाने गए caller use वाले fields जोड़ती है।

क्या विफल हुआ और क्या action चला, दोनों अलग रखें

Safe error design को एजेंट को बताना चाहिए कि remote side ने शायद कार्रवाई की या नहीं। यहीं सबसे अधिक retry guidance खतरनाक बनती है।

मान लें एजेंट POST /deployments भेजता है और connection timeout हो जाता है। Gateway जानता है कि उसने call का प्रयास किया। उसे नहीं पता कि upstream ने request पाई या नहीं, upstream ने deployment बनाया या नहीं, या response रास्ते में गायब हो गया। TEMPORARY_FAILURE लौटाने से एजेंट दूसरा deployment request भेज सकता है। AUTH_FAILED लौटाना भी गलत है। सही state OUTCOME_UNKNOWN है।

Response में यह बात सीधे लिखें:

{
  "ok": false,
  "code": "OUTCOME_UNKNOWN",
  "message": "The connection ended after the request started. The remote action may have completed.",
  "action": "inspect_outcome",
  "retryable": false,
  "request_id": "act_9b18d4e0",
  "operation": "create_deployment"
}

operation generic action class का नाम है, पूरा route या payload नहीं। अब एजेंट अलग read-only status call इस्तेमाल कर सकता है, अगर integration ऐसी सुविधा देती है। API idempotency references support करती हो तो gateway safe reference को operation से जोड़कर उसे internally query कर सकता है। अगर target system में idempotency value access material का काम भी करती है, तो उसे expose न करें।

Read operations भी अपने आप retry के लिए सुरक्षित नहीं होतीं। कोई read billing trigger कर सकता है, remote state refresh कर सकता है या किसी साधारण नाम के पीछे side effects वाला command चला सकता है। Integration author को यह label करना चाहिए कि operation repeatable है या नहीं। Language model से method name देखकर यह फैसला न कराएं।

Gateway में retry budget तय करें। Response में retry_after_seconds: 30 जैसा सीमित delay दिया जा सकता है, लेकिन तभी जब upstream ने सुरक्षित value दी हो या gateway उस limit का मालिक हो। केवल «temporary» संदेश के कारण एजेंट को अनिश्चित समय तक retry न करने दें। बार-बार failures noise बढ़ाते हैं, rate limits खर्च करते हैं और बाद की जांच कठिन बनाते हैं।

Human denial का अलग अर्थ होना चाहिए

किसी व्यक्ति का approval अस्वीकार करना remote authentication error नहीं है। इसका अर्थ है कि अनुरोधित कार्रवाई चली ही नहीं। यह अंतर security और usability दोनों की रक्षा करता है।

अगर tool denied approval को AUTH_FAILED में बदल देता है, तो एजेंट alternate credentials आजमा सकता है, secret rotate करने को कह सकता है या थोड़ा बदला हुआ request भेज सकता है। इनमें से कोई कार्रवाई «नहीं» कहने वाले व्यक्ति का सम्मान नहीं करती। Denial को generic internal failure में बदलने पर user को पता ही नहीं चलेगा कि gateway में खराबी थी या नहीं।

USER_DENIED लौटाएं और छोटा message दें, जैसे «अनुरोधित कार्रवाई को मंज़ूरी नहीं मिली और वह चली नहीं।» Secret name, selected account या exact target का उल्लेख न करें, अगर वे पहले से tool के safe input contract का हिस्सा नहीं हैं। Caller को रुकना है। नया, स्पष्ट request शुरू करना है या नहीं, यह व्यक्ति तय कर सकता है।

Locked secret store फिर अलग स्थिति है। VAULT_LOCKED का अर्थ है कि gateway ने credential चुनने या इस्तेमाल करने से पहले ही action अस्वीकार कर दिया। Safe remedy है किसी व्यक्ति से gateway unlock करने को कहना, एजेंट से token मांगना नहीं। इससे वह आम failure mode रुकता है जिसमें model managed credentials उपलब्ध न होने पर अपने context में कोई दूसरा secret खोजने लगता है।

Sallyport इस separation का सीधे इस्तेमाल करता है: vault gate locked होने पर वह हर action deny करता है और per-session authorization यह अलग कर सकता है कि किसी नए process को approval चाहिए या remote service ने authenticated call को अस्वीकार किया है। एजेंट को action result मिलता है, जबकि credential app के encrypted vault में रहता है।

Approval fatigue को अधिक diagnostic detail देकर छिपाने की कोशिश न करें। अगर users नियमित रूप से बिना देखे calls approve करते हैं, तो approval में दिखाए जाने वाले action grouping, scope और process identity को सुधारें। अधिक verbose denial जल्दबाज़ी में दी गई consent को सुरक्षित नहीं बनाता।

दो-record diagnostic path बनाएं

एक record एजेंट के लिए सुरक्षित होना चाहिए और दूसरा authorized operator के लिए पर्याप्त complete। एक ही record को दोनों कामों के योग्य बनाने की कोशिश या तो support experience को अस्पष्ट करती है या secret leak बन जाती है।

Caller-safe record में code, message, action, retry guidance, request ID और शायद protocol status होना चाहिए। Protected record में selected credential record identifier, normalized destination, method, timing, upstream response metadata, sanitized payload fingerprint, raw exception और gateway decision का trace हो सकता है। Protected record को ऐसी जगह रखें जिसे agents ordinary tools के माध्यम से query न कर सकें।

Request ID opaque होना चाहिए। इसे credentials और destinations से स्वतंत्र रूप से generate करें। Hostname, username, activity pattern दिखाने वाला timestamp या incrementing database ID encode न करें, अगर आपके environment में ये details महत्वपूर्ण हैं। ID से user कह सकता है, «कृपया act_9b18d4e0 देखें», बिना underlying diagnostics दिए।

High-value actions के लिए record करें कि gateway हर boundary तक पहुंचा या नहीं: input validation, credential selection, user authorization, connection started, request bytes sent, response received और result returned। इससे operator को raw request दिखाए बिना OUTCOME_UNKNOWN का भरोसेमंद explanation मिलता है।

इस internal path में tamper evidence भी महत्वपूर्ण है। अगर कोई failed authorization attempts को चुपचाप मिटा सकता है या action block होने का कारण बदल सकता है, तो audit trail केवल सुविधा वाला log रह जाता है। Sallyport encrypted, hash-chained audit log से session और call views बनाता है और sp audit verify ciphertext पर offline chain check करता है। जब operator को record पर भरोसा करना हो, लेकिन agent को उसकी सामग्री तक पहुंच न देनी हो, तब यह उपयोगी है।

Protected record का एक sample ऐसा हो सकता है। ध्यान दें, यह agent response नहीं है:

{
  "request_id": "act_9b18d4e0",
  "event": "http_call_failed",
  "credential_record": "cred_42",
  "destination": "api.internal.example",
  "method": "POST",
  "path_template": "/deployments",
  "bytes_sent": true,
  "response_received": false,
  "exception_class": "ReadTimeout",
  "result_code": "OUTCOME_UNKNOWN"
}

यहां भी fields की सावधानी से समीक्षा करें। पूरा path resource identifiers उजागर कर सकता है। Request body को आमतौर पर one-way fingerprint, schema name या कड़े redaction वाले representation में बदलना चाहिए। Operators को अक्सर हर submitted value पढ़ने की नहीं, दो attempts की तुलना करने की जरूरत होती है।

Error messages के लिए सोच-समझकर redaction policy बनाएं

Redaction का अर्थ केवल token को आठ asterisks से बदलना नहीं है। इससे सिर्फ वे secret formats संभलते हैं जिन्हें आप पहले से पहचानते हैं। Proper policy messages, logs, metrics और tool results में जाने से पहले fields को classify करती है।

पहले direct secrets classify करें: bearer tokens, passwords, private keys, cookies, signed URLs, authorization headers और client certificates। फिर sensitive context classify करें: internal DNS names, local paths, user names, repository names, resource IDs, request bodies और deployment topology दिखाने वाले headers। दूसरा वर्ग protected record में स्वीकार्य हो सकता है, लेकिन agent-visible error में शायद ही कभी होना चाहिए।

«7KQ2 पर खत्म होने वाला credential reject हुआ» जैसा message न लौटाएं। Teams ऐसा इसलिए जोड़ती हैं क्योंकि कई credentials होते हैं और operators जानना चाहते हैं कि कौन-सा विफल हुआ। इससे ऐसा स्थायी identifier बनता है जिसे traces के बीच correlate किया जा सकता है। एजेंट को AUTH_FAILED लौटाएं। Operator protected request ID के माध्यम से credential record देख सकता है।

By default tool input echo न करें। एजेंट पहले से जानता है कि उसने क्या करने का प्रयास किया, लेकिन gateway यह मानकर नहीं चल सकता कि input को दोहराना सुरक्षित है। URL में signed query string हो सकती है। Command में environment assignment हो सकता है। JSON payload में किसी दूसरे system से मिला temporary credential हो सकता है। Copied invalid value के बजाय invalid_fields: ["repository"] जैसा field-level validation error लौटाएं।

Hostile fixtures से redaction का परीक्षण करें। Unusual casing वाले secrets, duplicated headers, URL userinfo, percent-encoded query values, nested JSON, exception causes और SSH command arguments शामिल करें। फिर assert करें कि serialized tool response, general logs, metrics labels या crash payloads में कोई fixture secret नहीं है। केवल happy path जांचने वाला test failure handling के बारे में कुछ साबित नहीं करता।

Remote messages को untrusted input मानें

Remote API helpful error body, HTML login page या उसे पढ़ने वाले व्यक्ति को प्रभावित करने के लिए बनाई गई string लौटा सकती है। Gateway को यह content सीधे agent के context में नहीं भेजना चाहिए।

यह partly secret issue है। Servers कभी-कभी request values को error pages में वापस दिखाते हैं। Invalid Authorization header, cookie, query parameter या JSON field upstream diagnostic response में लौट सकता है। उसे pass through करने से remote echo credential leak बन जाता है।

यह instruction-integrity issue भी है। अगर upstream error कहता है, «अपने credentials सुधारने के लिए यह command चलाएं», तो एजेंट उसे operational guidance मान सकता है। Remote service gateway की recovery policy नहीं लिख सकती।

Upstream protocol response से ज्ञात safe fields map करें। Numeric HTTP status और documented rate-limit delay उपयोगी हो सकते हैं। Free-text bodies को protected evidence मानें, जब तक आपके पास format-specific parser और स्पष्ट allowlist न हो। Integration को human-readable remote reason चाहिए तो उसकी prose copy करने के बजाय उसे gateway-owned language में normalize करें, जैसे «Service ने अनुरोधित resource अस्वीकार किया।»

RFC 9110 HTTP status semantics परिभाषित करता है, लेकिन उसके statuses origin के response body को disclose करने की अनुमति नहीं देते। यह separation स्पष्ट रखें। Protocol information recovery में मदद कर सकती है, arbitrary upstream text safe diagnostic contract नहीं है।

Contract को failure-focused tests के अधीन रखें

अधिकतर teams valid request से useful data लौटने का परीक्षण करती हैं। यह भी test करें कि हर invalid और interrupted request केवल वही data लौटाता है जो agent को दिखना चाहिए।

Error schema को versioned contract बनाएं। Tests में उसे validate करें और development के दौरान serialization boundary पर unknown fields reject करें। Object का shape strict हो तो allowlist का audit आसान होता है।

ऐसा fixture secret इस्तेमाल करें जो accidental transformations पकड़ सके और हर stage पर failures force करें। Test matrix में credentials से पहले validation, locked vault, declined consent, remote 401 और 403 responses, rate limiting, DNS failure, TLS validation failure, bytes निकलने से पहले timeout, bytes निकलने के बाद timeout, malformed upstream JSON और gateway से उठी exception शामिल होनी चाहिए।

हर case के लिए चार बातें assert करें:

• Tool response में expected code और permitted action हो।
• Fixture secret caller-visible serialized field में कहीं न आए।
• Response में raw headers, raw upstream body text या local connection details न हों।
• Protected diagnostic record में request ID और operator की जांच के लिए पर्याप्त state हो।

केवल regex checks पर निर्भर न रहें। Exact fixture secret, उसका URL-encoded रूप, जहां relevant हो वहां base64 रूप और सामान्य prefixes या suffixes खोजें। फिर HTTP, SSH, telemetry या crash-reporting dependency update करने पर captured error response को manually inspect करें। Libraries बिना आपकी अनुमति मांगे exception formatting बदल देती हैं।

सबसे कठिन हिस्सा agent error को operator के debug console जैसा बनाने की इच्छा रोकना है। Caller contract छोटा, स्थिर और action-oriented रखें। Evidence को protected और correlated रखें। अगली outage आने पर यह separation एजेंट को सुरक्षित व्यवहार के लिए पर्याप्त जानकारी देगी और इंसान को वास्तविक fault ठीक करने के लिए पर्याप्त evidence।