Status endpoint polling: एजेंट बिना loops के कैसे इंतज़ार करते हैं

External job शुरू करने वाला एजेंट लगातार यह नहीं पूछ सकता कि «क्या अब हो गया?» और तब तक पूछता रहे, जब तक provider, budget या कोई व्यक्ति हार न मान ले। Status endpoint polling के लिए स्पष्ट contract चाहिए: progress किसे मानेंगे, अगला request कब भेजा जा सकता है, इंतज़ार कब खत्म होगा और उसके बाद क्या करना है, यह कौन तय करेगा।

मैंने कई बार देखा है कि मामूली लगने वाली status checks सैकड़ों calls में बदल जाती हैं। Job identifier सही था, endpoint हर बार HTTP 200 लौटा रहा था और किसी ने एजेंट को यह नहीं बताया था कि deadline के बाद «running» स्वीकार्य उत्तर नहीं है। इसका समाधान कोई चालाक scheduling नहीं है। इंतज़ार को प्रमाण और escalation path वाली सीमित कार्रवाई बनाना ही समाधान है।

Running status इंतज़ार की अनुमति है, कार्रवाई की नहीं

Nonterminal job state का अर्थ है कि बाद में फिर observation की जा सकती है। इसका अर्थ यह नहीं है कि एजेंट output fetch कर सकता है, dependent work शुरू कर सकता है, original submission दोबारा भेज सकता है या अपना अधिकार बढ़ा सकता है।

यह फर्क महत्वपूर्ण है, क्योंकि asynchronous APIs अक्सर हर state के लिए successful HTTP response देती हैं। ऐसा response status endpoint के काम करने की पुष्टि करता है, job के सफल होने की नहीं।

{
  "job_id": "exp_71c",
  "state": "running",
  "updated_at": "2025-04-18T10:24:00Z"
}

HTTP result और job result को दो अलग तथ्यों की तरह देखें। पहला सवाल है, «क्या provider ने इस request का उत्तर दिया?» दूसरा है, «क्या workflow आगे बढ़ सकता है?» Teams अक्सर दोनों को मिला देती हैं। फिर एजेंट अधूरा export download कर लेता है या ऐसा परिणाम post कर देता है जो कभी बना ही नहीं।

हर provider integration के लिए एक छोटी state table लिखें। status जैसे field name से अर्थ का अनुमान न लगाएं, क्योंकि providers एक ही शब्द का इस्तेमाल बहुत अलग lifecycles के लिए करते हैं। उपयोगी table में ये categories हों:

• Pending states बाद में status request की अनुमति देती हैं, जैसे queued, running या processing।
• Success states केवल उस नामित follow-up action की अनुमति देती हैं, जैसे result URL retrieve करना।
• Failure states run रोकती हैं और provider error सुरक्षित रखती हैं।
• Cancellation और expiry states run रोकती हैं। दोबारा submission तभी करें जब कोई व्यक्ति स्पष्ट रूप से कहे।
• Unknown states run रोकती हैं, क्योंकि integration सुरक्षित रूप से अनुमान नहीं लगा सकती कि paused, awaiting_review या कोई नया value harmless है।

Status response में contradictions भी जांचें। succeeded कहने वाली job में जरूरी result reference न हो, तो वह इस्तेमाल के लिए तैयार नहीं है। अपनी बताई हुई expiry time के बाद भी running कहने वाली job को अधिक polling नहीं, escalation चाहिए।

Job ID, provider account context, original request fingerprint और अपेक्षित terminal states को साथ रखें। यह association खो जाने पर restart के बाद एजेंट गलत job poll कर सकता है या पहले के request की job को current job समझ सकता है।

Fixed intervals synchronized pressure बनाते हैं

Fixed interval code में साफ दिखता है, लेकिन fleet में खराब व्यवहार करता है। अगर पचास एजेंट लगभग एक ही मिनट में काम submit करें और हर दस सेकंड में poll करें, तो वे provider पर समूहों में पहुंचेंगे। छोटी outage के बाद भी ये समूह बने रहेंगे, क्योंकि हर एजेंट उसी clock पर retry करेगा।

बढ़ता हुआ delay और jitter इस्तेमाल करें। Short delay तभी रखें जब provider आम तौर पर जल्दी पूरा होता हो या तुरंत नया status देता हो। हर pending response के बाद प्रतीक्षा बढ़ाएं, उसे cap करें और हर run में actual delay अलग रखें।

एक व्यावहारिक schedule यह हो सकता है:

base_delay = 5 seconds
max_delay = 120 seconds
attempt = number of completed polls
raw_delay = min(max_delay, base_delay * 2^attempt)
actual_delay = random value between 50% and 100% of raw_delay

Random range महत्वपूर्ण है। 5, 10, 20, 40 और 80 seconds की deterministic sequence synchronization को सिर्फ बड़ी waves में बदलती है। कुछ systems में full jitter भी काम करता है, जहां random value zero से cap तक कहीं भी हो सकती है। Job polling के लिए मैं lower bound पसंद करता हूं, क्योंकि बार-बार near-zero delay चुनने वाला run retry storm जैसा दिखने लगता है।

Job duration को ध्यान में रखे बिना generic backoff schedule न लगाएं। जो document conversion आम तौर पर एक मिनट में पूरी हो जाती है, उसे शुरुआती observations से लाभ होगा। Estimated completion time देने वाले batch export को हर कुछ seconds में status call नहीं मिलनी चाहिए, सिर्फ इसलिए कि एजेंट खाली महसूस कर रहा है।

अगर API next_check_at, poll_after_seconds या ऐसा कोई field देती है, तो उसे provider guidance मानें। स्वीकार करने से पहले उसे validate करें। Negative values, operation deadline से अधिक लंबे absurd waits और parse न हो सकने वाले timestamps अस्वीकार करें। एजेंट बताए गए समय या अपनी deadline तक, जो पहले आए, इंतज़ार कर सकता है।

Delay का अर्थ यह वादा नहीं है कि एजेंट ठीक उसी क्षण request करेगा। Local process sleep कर सकता है, restart हो सकता है, connectivity खो सकता है या बहुत देर बाद resume हो सकता है। जागने पर पहले देखें कि deadline निकल चुकी है या नहीं। Missed intervals की भरपाई के लिए कई status calls एक burst में न भेजें।

Deadline और request budget अलग failures पकड़ते हैं

हर polling run में wall-clock deadline और status requests की maximum संख्या दोनों होनी चाहिए। अगर provider remote या unreliable है, तो transport failures के लिए अलग cap रखें।

Deadline तय करती है कि workflow कितनी देर तक unresolved रह सकता है। यह एजेंट को stale task को पूरे weekend तक जीवित रखने से रोकती है, सिर्फ इसलिए कि API अब भी queued कह रही है। Deadline business delay के प्रभाव, provider की documented retention period और उस समय से चुनें जब किसी व्यक्ति को फैसला करना चाहिए। इसे सिर्फ average runtime से न निकालें, क्योंकि averages अटकने वाली jobs को छिपा देती हैं।

Request budget provider और इस्तेमाल किए गए credential पर एजेंट का दबाव नियंत्रित करता है। समय धीरे बीते तब भी यह scheduling bug पकड़ता है और API calls पर शुल्क हो तो cost सीमित करता है। Network ambiguity के बाद की status calls भी budget में गिनें। अगर ऐसा नहीं करेंगे, तो एजेंट provider quota खत्म कर सकता है और खुद को समझा सकता है कि उसने केवल कुछ attempts किए हैं।

Failure budget का काम अलग है। इसमें connection refusals, DNS errors, TLS failures और 5xx responses गिनें, जिनसे एजेंट job state जान नहीं पाता। एक timeout से job failure साबित नहीं होता। एक घंटे तक वही failed request दोहराने से धैर्य साबित नहीं होता।

पहली poll से पहले इस जैसा operation record durable storage में रखें:

{
  "operation_id": "report-export-2025-04-18-01",
  "provider_job_id": "exp_71c",
  "started_at": "2025-04-18T10:20:00Z",
  "deadline_at": "2025-04-18T11:00:00Z",
  "max_status_requests": 12,
  "max_transport_failures": 3,
  "status_requests_used": 0,
  "transport_failures_used": 0,
  "last_known_state": "queued"
}

ये values उदाहरण हैं, हर provider के defaults नहीं। Forty minutes में twelve checks slow export के लिए ठीक हो सकते हैं। तीन seconds में पूरी होने वाली operation के लिए यह बेवकूफी होगी और उस operation के लिए खतरनाक होगी जिसे provider हर पंद्रह मिनट में एक बार check करने को कहता है।

Request से पहले deadline जांचें, केवल request के बाद नहीं। वरना देर से जागा process अनधिकृत extra call कर सकता है। Scheduling से ठीक पहले request budget जांचें और transmission से ठीक पहले उसे बढ़ाएं। Process scheduling और sending के बीच crash हो जाए तो यह क्रम महत्वपूर्ण है। कभी-कभार unused reservation बेहतर है, invisible extra request नहीं।

Stop conditions executable होनी चाहिए, केवल इच्छा नहीं

«बहुत देर लगे तो रुकें» इंसान के लिए note है, जिसे एजेंट लागू नहीं कर सकता। Stop conditions को current record और response पर आधारित predicates की तरह लिखें।

सफलतापूर्वक तभी रुकें जब provider accepted terminal success state दे और अगले action के लिए जरूरी हर field validation पास करे। अगला action artifact download करना हो तो success घोषित करने से पहले artifact reference validate करें। अगला action किसी दूसरे system को प्रभावित करता हो तो उसे करने से पहले terminal response record करें।

Provider terminal failure दे, response parse न हो या state integration की allowlist से बाहर हो, तो failure के साथ रुकें। Unknown state को authorization denial जितनी गंभीरता दें। Provider बिना warning needs_payment, manual_review या blocked state जोड़ सकता है। उसे «wait» मान लेना provider-side software change को आपकी तरफ endless loop बना देता है।

Deadline आते ही timeout के साथ रुकें, भले status अभी बदली हो। एजेंट आखिरी observed state report करे, लेकिन केवल progress जैसी चीज देखकर खुद को एक और पूरा delay न दे। अधिक इंतज़ार स्वीकार्य हो तो नई deadline के साथ नया authorization decision लें।

अगली status request allowed count से अधिक हो तो budget exhaustion के साथ रुकें। Agent restart, session change या नया prompt मिलने पर count reset न करें। Provider को आपका internal process boundary नहीं, एक caller और एक job दिखता है।

Status request timeout होने के बाद failure budget खत्म हो गया हो, तो ambiguous delivery के साथ रुकें। Agent नहीं जान सकता कि provider ने request पाई या नहीं, लेकिन status requests दोहराना सुरक्षित होना चाहिए। अगर endpoint हर GET पर state बदलता है, पैसे charge करता है या artifact refresh करता है, तो operational sense में वह status endpoint नहीं है। उसे action मानें और मजबूत controls लगाएं।

यहीं teams महंगी गलती करती हैं: वे मान लेती हैं कि GET harmless है। HTTP में GET semantic sense में safe method है, यानी client ने state change का अनुरोध नहीं किया। यह server के लिए निभाने वाला contract है, URL की कोई जादुई property नहीं। किसी call को observational मानने से पहले test account और provider documentation से व्यवहार सत्यापित करें।

Providers के protocol signals का सम्मान करें

HTTP में कुछ signals हैं जिन्हें एजेंट की polling behavior तुरंत बदलनी चाहिए। Loop का अपना timer होने के कारण उन्हें अनदेखा करना provider के प्रति असम्मानजनक है और recovery को आम तौर पर धीमा करता है।

RFC 9110 Retry-After को उस minimum time के संकेत के रूप में परिभाषित करता है, जिसका client को follow-up request से पहले इंतज़ार करना चाहिए। Field में seconds का delay या HTTP date हो सकती है। दोनों forms parse करें। Status request को 503 और Retry-After: 120 मिले तो सामान्य thirty-second backoff लगाकर जल्दी retry न करें। Operation deadline अनुमति देती हो तो कम से कम दो मिनट रुकें।

RFC 6585 HTTP 429, Too Many Requests, को परिभाषित करता है और कहता है कि response में Retry-After हो सकता है। Provider header छोड़ सकता है, इसलिए एजेंट को अपना backoff भी चाहिए। Guidance के बिना 429 मिलने पर delay तेज़ी से बढ़ाएं और उसे अपने failure या rate-limit budget में गिनें। लगातार 429 मिलने पर run को escalate करें, timer को अनिश्चित रूप से न बढ़ाते रहें।

202 Accepted के लिए response body और headers में location, job ID और बताई गई status resource देखें। Submission endpoint से guessed URL न बनाएं। कुछ providers result location, कुछ status location देते हैं और कुछ बाद में final representation लौटाते हैं। Documented contract का पालन करें।

404 का हमेशा यह अर्थ न निकालें कि job कभी बनी ही नहीं। नई submitted job eventually consistent हो सकती है और पूरी हो चुकी job retention expire होने के बाद गायब हो सकती है। कौन-सी explanation संभव है, यह original provider contract तय करता है। Documentation इसे न समझाए तो इसे integration failure मानकर job ID और timestamps के साथ escalate करें।

401 या 403 पर polling रोक दें। उसी credential से authorization failures दोहराने पर noise बढ़ता है और provider defenses सक्रिय हो सकती हैं। Human action access, credential rotation, account scope या gateway configuration जांचना है। Polling action समाप्त हो चुका है।

5xx responses और network failures के लिए transport failure budget इस्तेमाल करें। Response code, request timestamp और provider request ID सुरक्षित रखें। Support या operator को lost response और job failure में फर्क करना हो तो ये details महत्वपूर्ण होंगी।

Escalation को decision मांगना चाहिए, log नहीं फेंकना चाहिए

एजेंट के पास ऐसा स्पष्ट point होना चाहिए जहां वह इंतज़ार रोककर व्यक्ति या किसी स्पष्ट रूप से authorized workflow को स्थिति सौंप दे। Escalation कोई decorative notification नहीं है, जो हर retry खत्म होने के बाद भेजी जाए।

Escalation reason machine-readable बनाएं। deadline_exceeded, request_budget_exhausted, rate_limited, unknown_state, authorization_denied या provider_failure जैसी categories इस्तेमाल करें। हर category अगली allowed action तय करे। unknown_state देखने वाला व्यक्ति temporary pause मंज़ूर कर सकता है, जबकि कोई provider changes जांचे। authorization_denied पर वही request फिर मंज़ूर नहीं करनी चाहिए।

Escalation message में निर्णय लेने लायक context हो, लेकिन secrets न हों:

External job needs a decision
Operation: report-export-2025-04-18-01
Provider job: exp_71c
Last state: running
Elapsed time: 40 minutes
Status requests: 12 of 12
Last HTTP result: 200 at 10:58 UTC
Stopped because: request_budget_exhausted
Safe options: extend waiting once, cancel at provider, inspect provider console

Choice को «continue?» की तरह न लिखें। इससे operator indefinite loop मंज़ूर कर सकता है। सीमित options दें। «चार additional checks के साथ fifteen minutes बढ़ाएं» cost बताता है और नई limit बनाता है। «Cancel at provider» तभी दिखाएं जब integration में documented cancellation action हो और operator उसके प्रभाव समझता हो।

अगर eventual result की usefulness window छोटी है तो पहले escalate करें। Deployment window बंद होने के बाद मिलने वाली deployment validation शायद अधिक polling के लायक न हो। Tax document export provider incident के दौरान इंतज़ार के लायक हो सकता है। केवल technical state priority तय नहीं कर सकती, इसलिए जहां जरूरी हो वहां workflow business deadline को provider job deadline से अलग encode करें।

Provider idempotency देता हो और आप idempotency token persist करते हों, तभी timeout के बाद automatic resubmission करें। Polling failure से original job failure साबित नहीं होता। Resubmission duplicate invoices, emails, deployments या competing exports बना सकती है। लोग इसे «self-healing» कहते हैं, जब तक उन्हें cleanup न करना पड़े।

Polling controller को durable state और एक owner चाहिए

विश्वसनीय polling controller अपना record persist करता है और सुनिश्चित करता है कि एक समय में केवल एक worker job का owner हो। इन दोनों के बिना restart recovery और parallel agents duplicate checks या contradictory follow-up actions बनाएंगे।

Owner process lease, database lock या आपके environment के लिए उपयुक्त किसी durable mechanism से बन सकता है। Worker मर जाए तो mechanism expire होना चाहिए और नए owner को कुछ भेजने से पहले पूरा record reload करना चाहिए। दूसरा agent process मौजूद हो तो साधारण in-memory boolean ownership नहीं है।

हर meaningful event के बाद persist करें: job submission, scheduled next check, sent status request, received response, state transition और escalation। हर debug detail के लिए अलग journal जरूरी नहीं, लेकिन authority और budgets को प्रभावित करने वाले facts recover होने चाहिए।

यह pseudocode accidental loops रोकने वाला क्रम दिखाता है:

load operation
if operation is terminal or escalated:
    exit
if current_time >= operation.deadline_at:
    record timeout and escalate
    exit
if operation.status_requests_used >= operation.max_status_requests:
    record budget exhaustion and escalate
    exit
if current_time < operation.next_poll_at:
    schedule wakeup and exit

acquire ownership lease
reload operation
increment status_requests_used and persist
send one status request
persist response metadata

if response has terminal success and required result fields are valid:
    record success
else if response has terminal failure or unknown state:
    record stop reason and escalate
else if response requires waiting:
    calculate next_poll_at with provider guidance, backoff, and jitter
    persist next_poll_at
else:
    record integration failure and escalate

Ownership लेने के बाद दूसरा load जानबूझकर है। Lease के लिए यह worker प्रतीक्षा कर रहा था, उसी दौरान दूसरा worker job पूरी कर चुका हो सकता है। इसे skip करेंगे तो अंततः दो agents एक ही result retrieve या publish करेंगे।

Sleep करते समय lease न पकड़े रहें। केवल record update और one request send करते समय lease रखें, यदि आपका ownership design इसे सुरक्षित मानता हो। Slow external job की पूरी अवधि के लिए lease पकड़ना laptop sleep या process death के बाद orphan problem बन जाता है।

Agent के दृष्टिकोण से status endpoint read-only रहना चाहिए। Output retrieval, cancellation और downstream publication को अपनी records वाली अलग actions रखें। इन्हें एक polling function में मिलाना ही harmless timer को hidden workflow engine में बदलता है।

Human approval escalation boundary पर होना चाहिए

Routine polls को human click की जरूरत नहीं होती, यदि वे original approved operation, credential scope, deadline और request budget के भीतर रहें। हर read के लिए approval मांगने पर लोग बिना पढ़े approve करना सीखते हैं और बिना security benefit के काम धीमा होता है।

Approval तब चाहिए जब एजेंट नई authority boundary मांगे: original deadline से अधिक समय, बड़ा request budget, cancellation call, resubmission, अलग credential या validation fail हुए output का इस्तेमाल। ये operation में बदलाव हैं, ordinary observations नहीं।

Sallyport MCP-capable agent से API credential छिपा सकता है, जबकि app status call करती है और result लौटाती है। इसका per-call key setting उन operations के लिए उपयोगी है जहां किसी credential का हर उपयोग, status request समेत, explicit approval मांगता है। लेकिन यह setting unbounded polling design ठीक नहीं कर सकती।

Approval model consequence के आधार पर चुनें। Low-risk provider status call per-session authorization में रह सकती है। Sensitive job metadata दिखाने वाले privileged status API को per-call approval या narrower credential चाहिए। दोनों स्थितियों में request authorize करने का तरीका चुनने से पहले controller की limits तय करें।

Deadline extension harmless है या नहीं, यह prompt को तय न करने दें। Request में current state, elapsed time, attempted calls, proposed extra budget और continue करने का expected effect होना चाहिए। Reviewer तब ऐसी extension अस्वीकार कर सकता है जो release window miss करे या stale data बनाए।

केवल request नहीं, wait करने के decision का audit करें

Request log बताता है कि एजेंट ने /jobs/exp_71c call किया। वह यह नहीं बताता कि call polling plan के अनुसार allowed थी या नहीं, एजेंट ने Retry-After अनदेखा किया या job पहले ही deadline पार कर चुकी थी।

हर call के साथ controller decision record करें: current state, next scheduled time, delay source, request count, deadline, response code, parsed job state और resulting decision। Delay source provider_retry_after, provider_poll_hint, local_backoff या manual_extension हो सकता है। Incident के बाद बहस में यह छोटा field बहुत समय बचाता है।

Useful audit sequence कहानी की तरह पढ़ी जा सकती है:

10:20:00 submitted job exp_71c, deadline 11:00:00, budget 12
10:20:05 polled, state queued, next poll 10:20:14 from local backoff
10:20:14 polled, state running, next poll 10:20:31 from local backoff
10:20:31 received 503, Retry-After 120, next poll 10:22:31 from provider guidance
10:22:31 polled, state running, next poll 10:23:48 from local backoff
10:58:00 polled, state running, request budget exhausted, escalated

यह record खराब controller को साफ दिखाता है। अगर timestamps provider delay के बावजूद हर second एक request दिखाएं, तो आपके पास प्रमाण है। अगर एजेंट कहे कि job timed out हुई, लेकिन final state succeeded थी, तो सुधारने के लिए ठोस जानकारी मौजूद है।

Sallyport agent sessions और individual calls को encrypted, hash-chained audit log में project करता है और sp audit verify ciphertext पर offline उस chain को verify कर सकता है। ऐसा प्रमाण तभी सबसे उपयोगी होता है जब आपका अपना operation record बताए कि हर observed call क्यों हुई।

Polling quality को इस आधार पर न मापें कि jobs अंततः पूरी हुईं या नहीं। देखें कि हर job terminal result या bounded escalation तक पहुंचती है या नहीं, agents provider के waiting instructions मानते हैं या नहीं और operator disputed decision को reconstruct कर सकता है या नहीं। Uncontrolled loop में मैं पहला बदलाव यही करूंगा: एजेंट की पहली status request से पहले deadline और request budget persist करना।