AI agents के लिए API pagination: सीमित discovery

Page budget के बिना list endpoint को call करने वाला agent discovery नहीं कर रहा। वह एक खुले-ended remote procedure को शुरू कर रहा है और उम्मीद कर रहा है कि bill, rate limit और result set उसके पक्ष में रहेंगे। दूसरी गलती भी उतनी ही नुकसानदेह है: page one fetch करना, plausible answer देखना और चुपचाप उसे पूरे system का जवाब मान लेना।

Pagination यह तय करती है कि agent ईमानदारी से क्या दावा कर सकता है। लौटाया गया item साबित करता है कि वह item मौजूद है। इससे यह साबित नहीं होता कि और कोई item नहीं है। कोई item न मिलना भी बहुत कम साबित करता है, जब तक agent यह न दिखा सके कि उसने कितना scope inspect किया, किस ordering पर भरोसा किया और server ने completion का संकेत क्यों दिया।

मैंने agents को «stale access tokens खोजो» जैसे मामूली अनुरोध को हजारों calls में बदलते देखा है, क्योंकि किसी ने नहीं बताया कि discovery कहाँ खत्म होती है। मैंने one-page inventory के बाद page two पर मौजूद accounts को साफ करने की कोशिश भी देखी है। इसका उपाय चतुर prompt wording नहीं है। Agent को bounded traversal contract दें और उसकी final report में boundary साफ दिखाएँ।

Discovery calls के लिए स्पष्ट budget जरूरी है

हर paginated discovery call के लिए ऐसी limits चाहिए जिन्हें agent चुपचाप बढ़ा न सके। पहली request से पहले maximum pages, लौटाए जाने वाले records की अधिकतम संख्या, deadline और rate-limit allowance तय करें। सही values task पर निर्भर करती हैं, लेकिन limits का होना जरूरी है।

Discovery को action से अलग phase मानें। Discovery के दौरान agent identifiers और facts जुटाता है। केवल इसलिए objects को delete, rotate या modify नहीं करना चाहिए कि किसी एक page में कुछ संदिग्ध दिखा। पर्याप्त evidence मिलने पर agent scoped plan पेश कर सकता है या अलग से authorized action phase शुरू कर सकता है।

एक उपयोगी contract के चार हिस्से होते हैं:

• Endpoint और सभी filters, साथ में sort order, यदि API इसकी अनुमति देती हो।
• Page size और pages या records की ceiling।
• API द्वारा तय completion condition, जैसे next cursor का न होना।
• Early-stop condition, जैसे किसी नामित object का मिलना या तय budget खत्म होना।

Record cap को page cap न समझें। यदि service एक page में 100 records देती है और agent की cap 500 records है, तो पांच calls काफी हो सकती हैं। Filtering या permissions के कारण service effective page size घटा दे, तो उसी काम के लिए अधिक calls लग सकती हैं। अच्छा implementation हर response के बाद दोनों limits जाँचता है।

मसलन, billing-service नाम का repository खोजने को कहा गया agent exact match मिलते ही रुक सकता है, यदि endpoint का filter और ordering ऐसा निष्कर्ष सुरक्षित बनाते हों। लेकिन branch protection के बिना हर repository पहचानने को कहा गया agent पहले match पर नहीं रुक सकता। उस task के लिए पूरी enumeration या स्पष्ट partial result चाहिए।

«All» शब्द की कीमत होनी चाहिए। Agent इसका इस्तेमाल तभी करे जब traversal server की terminal condition तक पहुँच जाए और page, record, time या error budget में से कोई भी limit न लगी हो। इनमें से कोई limit लग जाए, तो report में «partial scan» लिखें और boundary बताएं।

Page size cost control है, completeness setting नहीं

limit, per_page या page_size parameter service को बताता है कि एक response में कितने records लौटाने की कोशिश करनी है। यह नहीं बताता कि agent को collection का कितना हिस्सा inspect करना है। इसे maximum पर रखने से कुछ round trips कम हो सकते हैं, लेकिन हर response इतना महँगा हो सकता है कि timeout हो जाए, context budget पार हो जाए या अप्रासंगिक data की भीड़ में जरूरी details छिप जाएँ।

उस decision के लिए जरूरी सबसे छोटा page चुनें। यदि agent को एक exact account चाहिए, तो 1,000 full objects के बजाय 20 संक्षिप्त records माँगना आम तौर पर बेहतर है। Inventory बनानी हो, तो बड़े supported page size का इस्तेमाल तभी करें जब पुष्टि हो जाए कि endpoint सीमित और उपयोगी representation लौटाता है।

Fields भी page size जितने ही महत्वपूर्ण हैं। कई APIs fields, include, expand या ऐसा ही कोई mechanism देती हैं। Discovery pass में identifiers, names, state, timestamps और decision को प्रभावित करने वाली एक property माँगें। Full detail केवल उन candidates के लिए fetch करें जिन्हें inspection की जरूरत है। इससे traffic घटता है और model के सामने गलत पढ़े जाने वाला incidental text भी कम रहता है।

जब provider cursor pagination support करता हो, तो request का रूप ऐसा हो सकता है:

GET /v1/projects?state=active&limit=50&sort=id HTTP/1.1
Authorization: Bearer injected-by-gateway
Accept: application/json

और output shape records को continuation state से अलग रख सकती है:

{
  "data": [
    {"id": "prj_104", "name": "billing-service", "state": "active"}
  ],
  "next_cursor": "eyJvcmRlciI6ImlkIiwicG9zIjoiMTA0In0"
}

Agent को दर्ज करना चाहिए कि उसने 50 records माँगे और एक मिला। उसे छोटी array से completion का निष्कर्ष नहीं निकालना चाहिए। इस उदाहरण में उपयोगी completion signal केवल next_cursor का न होना या उसका documented null value है।

«Always use 100» जैसी मनमानी rule से बचें। Maximum page size हर API में अलग होती है और कुछ services expanded child objects या response bytes को अलग-अलग limits में गिनती हैं। Documented maximum तभी माँगें जब task को उससे लाभ हो। Broad scans में medium page size अक्सर बेहतर checkpoints, आसान retries और मानव द्वारा audit की जा सकने वाली reports देती है।

Cursors को opaque server state की तरह रखें

Cursor कोई fancy नाम वाला offset नहीं है। उसका अर्थ server तय करता है और agent को उसे byte for byte अगली request में copy करना चाहिए। उसमें sort position, snapshot identifier, permission boundary या signature encoded हो सकती है। उसका Base64 जैसा दिखना उसे decode, edit या खुद बनाने की अनुमति नहीं देता।

सुरक्षित loop सरल है: stable filters और sort parameters के साथ पहला page माँगें, response से मिला cursor save करें, फिर उसी query को cursor के साथ submit करें। हर original parameter बनाए रखें, जब तक API documentation स्पष्ट रूप से कुछ और न कहे। Requests के बीच filter बदलने से cursor invalid हो सकता है या, इससे भी खराब, plausible लेकिन discontinuous result set मिल सकता है।

request = { state: "active", limit: 50, sort: "id" }
seen_ids = set()
pages = 0

while pages < 10 and len(seen_ids) < 500:
    response = GET /v1/projects with request
    record response status, request, and response cursor

    for item in response.data:
        if item.id in seen_ids:
            report "duplicate record encountered" with item.id
            stop or apply the provider's documented recovery method
        seen_ids.add(item.id)

    pages += 1
    if response.next_cursor is absent:
        report "complete"
        break

    request.cursor = response.next_cursor
else:
    report "partial: traversal budget reached"

Duplicate check केवल दिखावे के लिए नहीं है। Agent के collection में आगे बढ़ते समय mutable collections बदल सकती हैं और pagination implementations में bugs हो सकते हैं। Duplicate का अर्थ हमेशा यह नहीं कि service fail हुई है, लेकिन agent को साफ enumeration होने का दिखावा बंद कर देना चाहिए। Provider snapshot token, as_of parameter या documented consistency mode देता हो, तो ऐसे jobs में उसका इस्तेमाल करें जिनसे consequential action होना है।

Cursor expiry के लिए स्पष्ट rule चाहिए। कुछ services cursors को थोड़े समय के लिए valid रखती हैं, जबकि कुछ उन्हें session से बाँधती हैं या query बदलने पर invalid कर देती हैं। Expired-cursor response मिलने पर agent को error save करना चाहिए और फिर stable checkpoint से restart करना चाहिए या scan को incomplete मानकर खत्म करना चाहिए। नए cursor का अनुमान लगाकर आगे नहीं बढ़ना चाहिए।

Restart से भी completeness का झूठा एहसास हो सकता है। पहले pass और restart के बीच records बदले हों, तो combined list में gaps या duplicates हो सकते हैं। Restart और resume के लिए इस्तेमाल की गई condition, जैसे created_at >= last_observed_timestamp, report में लिखें। Stable resume method न हो, तो बताएं कि traversal के दौरान collection बदल गई और result को deletion list की तरह इस्तेमाल न करें।

Collection बदलने पर offset pagination drift करती है

Offset pagination offset=200&limit=50 या page=5&per_page=50 जैसी संख्या इस्तेमाल करती है। इसे script करना और समझाना आसान है, इसलिए यह आज भी आम है। लेकिन जब agent collection में आगे बढ़ रहा हो और नए records जुड़ें या पुराने हटें, तो यह अविश्वसनीय हो जाती है।

मान लें page one newest-first order में records 1 से 50 लौटाता है। Agent के page two माँगने से पहले दस नए records आ जाते हैं। offset=50 अब नए records के बाद शुरू होगा और agent द्वारा पहले देखे गए objects के साथ overlap करेगा। अगर page one से records हटें, तो वही offset ऊपर खिसक चुके objects को छोड़ सकता है। केवल IDs deduplicate करके agent इसे ठीक नहीं कर सकता, क्योंकि deduplication repeats पकड़ती है, omissions नहीं।

API stable sort की अनुमति देती हो, तो deterministic tie breaker वाला sort चुनें। अकेला created_at अक्सर पर्याप्त नहीं होता, क्योंकि कई records का timestamp एक जैसा हो सकता है। Provider इसे document करता हो तो created_at,id जैसा sort agent को high-water mark दर्ज करने और अधिक सावधानी से resume करने देता है। API केवल offset देती हो और snapshot या stable ordering न देती हो, तो कई pages से निकाले गए निष्कर्षों में सावधानी रखें।

Complete answer चाहिए हो, तो भरोसे के क्रम में ये तरीके अपनाएँ:

1. Service से snapshot, export job या ऐसा cursor माँगें जो stable view को document करता हो।
2. Query को immutable time range तक सीमित करें और documented stable ordering इस्तेमाल करें।
3. दूसरा scan चलाकर identifiers की तुलना करें, फिर किसी disagreement की report करें।
4. Broad change करने के बजाय human से संकीर्ण और स्पष्ट scope approve कराएँ।

खराब interface को destructive workflow में न बदलें। Agent sampling, किसी खास object को खोजने या partial inventory बनाने के लिए offset pages इस्तेमाल कर सकता है। लेकिन unstable offset scan को इस प्रमाण के रूप में इस्तेमाल नहीं करना चाहिए कि हर matching credential, project या user मिल गया है।

Completion protocol से आना चाहिए, अंदाज़े से नहीं

अलग-अलग APIs pagination state को अलग जगहों पर दिखाती हैं। JSON body में next_cursor, has_more या अगले page का URL हो सकता है। कुछ APIs HTTP Link header इस्तेमाल करती हैं। RFC 8288 Web Linking और rel parameter को define करता है, जिनका इस्तेमाल next जैसे relationships के लिए होता है। Header relation देता है, यह गारंटी नहीं कि response body में कोई जाना-पहचाना cursor field भी होगा।

Agent को endpoint-specific completion rule चाहिए। इसे request definition के पास लिखें। उदाहरण के लिए: «Complete when next_cursor is null.» या: «Complete when no Link relation has rel="next".» यह न लिखें: «Complete when fewer than 100 records return.» Filtered pages, permission trimming, service caps और जानबूझकर uneven pages लौटाने वाली APIs में यह shortcut टूट जाता है।

एक सामान्य Link header ऐसा दिख सकता है:

Link: </v1/events?limit=100&cursor=a6f3>; rel="next",
      </v1/events?limit=100&cursor=first>; rel="first"

Agent को केवल वही relation चुनना चाहिए जिसे वह समझता हो। उसे पूरे header को जोड़ना नहीं चाहिए, first link को restart-safe checkpoint नहीं मानना चाहिए और missing last link से यह निष्कर्ष नहीं निकालना चाहिए कि final page नहीं है। API की अपनी documentation pagination contract तय करती है। RFC 8288 केवल यह बताता है कि link relations HTTP headers में कैसे travel करती हैं।

कुछ APIs खाली page के साथ has_more: true लौटाती हैं। Permission filter, concurrent deletion या delayed index मिलने तक यह अजीब लगता है। API इस behavior को document करती हो, तो budget रहने तक continuation token के साथ आगे बढ़ें और empty page दर्ज करें। Documentation न हो, तो रुकें और inconsistent pagination response flag करें। has_more true बने रहने के कारण हमेशा आगे बढ़ते रहना programming error है, persistence नहीं।

Terminal response और successful HTTP status को भी अलग समझें। 200 OK कहता है कि खास request सफल हुई। यह नहीं कहता कि collection खत्म हो गई। 404 का अर्थ expired cursor, गलत endpoint या गायब हो चुका resource हो सकता है। Status, response body और last cursor को run record में सुरक्षित रखें, ताकि human समझ सके कि इनमें से कौन-सी स्थिति हुई।

Partial result के साथ boundary statement जरूरी है

Agent को discovery की report वैसे लिखनी चाहिए जैसे सावधान operator incident note लिखता है: उसने क्या पूछा, क्या देखा और क्या inspect नहीं किया। अधिकांश खराब agent reports इसी आखिरी हिस्से में असफल होती हैं। वे findings तो गिनाती हैं, लेकिन stopped cursor, cap या error नहीं बतातीं, जिनसे पता चलता कि findings incomplete हैं।

ऐसा report format अपनाएँ जिसे human session दोबारा बनाए बिना इस्तेमाल कर सके:

Scope: GET /v1/projects?state=active&sort=id
Requested page size: 50
Pages fetched: 10
Records received: 487
Completion: partial
Stop reason: page budget reached
Last continuation cursor: eyJvcmRlciI6ImlkIiwicG9zIjoiNTg3In0
Observed finding: 12 projects matched the review rule
Uninspected scope: records after the last continuation cursor
Action taken: none

आखिरी line महत्वपूर्ण है। Discovery run को बताना चाहिए कि उसने कुछ बदला या नहीं। Report देखने वाले human को यह अनुमान नहीं लगाना चाहिए कि agent ने केवल objects list किए या उन पर action भी लिया।

यदि provider cursor को bearer capability मानता हो या उसके contents से account structure का पता चल सकता हो, तो sensitive cursor को chat transcript में न दिखाएँ। Exact token को protected run metadata में रखें और human-facing report में fingerprint या redacted prefix दिखाएँ। Agent को traversal resume या audit करने के लिए पर्याप्त state चाहिए, लेकिन लोगों को continuation tokens tickets और terminals में बिखरे हुए नहीं चाहिए।

यहाँ language risk को नियंत्रित करती है। «पहले inspect किए गए 500 records में कोई matching record नहीं मिला» सही है। «कोई matching record नहीं है» तभी सही है जब stable enough view पर complete traversal हो चुका हो। फर्क सुनने में मामूली लगता है, जब तक cleanup या compliance decision इसी पर निर्भर न हो।

Rate limits और retries के लिए अलग stopping rules चाहिए

Pagination rate-limit mistakes को बढ़ाती है, क्योंकि एक request loop बन जाती है। 429 Too Many Requests मिलने पर agent को उसी cursor के साथ endpoint पर लगातार वार नहीं करना चाहिए। Server Retry-After दे तो उसका सम्मान करें, wait को run deadline में गिनें और retry budget खत्म होने पर रुक जाएँ।

Timeout या 5xx response जैसी transient failures में आगे बढ़ने से पहले उसी page को retry करें। API list calls के लिए idempotency या request identifier support करती हो, तो documentation के अनुसार उसका इस्तेमाल करें। केवल इसलिए uncertain response के बाद अगले cursor पर न जाएँ कि request शायद सफल हुई हो। इससे silent hole बन जाता है।

Bounded retry policy में यह लिखा जा सकता है:

• Transient transport या server failures के बाद current page को अधिकतम दो बार retry करें।
• Rate limits के लिए Retry-After का सम्मान करें, यदि बची हुई deadline इसकी अनुमति देती हो।
• Authorization state बदले बिना authentication या authorization failures को retry न करें।
• Malformed pagination data, repeated cursor या undocumented continuation response पर रुक जाएँ।

Repeated cursor पर विशेष ध्यान दें। यदि page three वही next_cursor लौटाता है जिसे agent ने submit किया था, तो आगे बढ़ने से infinite loop बन सकता है। हर नए cursor की तुलना submitted cursor और पहले देखे गए cursors के set से करें। Repetition होने पर रुकें, जब तक provider किसी ऐसे मामले को document न करे जहाँ repetition अपेक्षित हो। ऐसा दुर्लभ है और इसके लिए provider-specific rule चाहिए।

Retry की जाँच के लिए agent को पर्याप्त response metadata रखना चाहिए, लेकिन secrets store नहीं करने चाहिए। Status code, request path, चुने हुए non-sensitive headers, page sequence number, cursor fingerprint, timestamps और policy अनुमति दे तो response body का digest दर्ज करें। Request fail होने पर authorization headers, full bearer tokens या credentials वाले URLs logs में न चिपकाएँ।

Failure walk-through बताता है कि page one खतरनाक क्यों है

मान लें agent से कहा गया है कि तय तारीख से पुराने हर inactive integration को disable करे। Integrations endpoint default रूप से 25 items देता है, most recently updated के हिसाब से sort करता है और केवल तभी next_cursor देता है जब और pages हों। Agent पहला page fetch करता है, तीन inactive integrations पाता है और उन्हें disable कर देता है। फिर वह report करता है कि उसने inactive integrations साफ कर दिए।

यह report दो कारणों से गलत है। Agent ने हर integration inspect नहीं किया और discovery के दौरान action लिया। तीन candidates मिलना page two के बाद की स्थिति के बारे में कुछ नहीं बताता। इससे भी बुरा, disable करने से updated_at बदल जाता है। Endpoint default sort इस्तेमाल करता हो, तो collection का order बदल सकता है। Agent ने अपना traversal खुद कम stable बना दिया।

सुरक्षित run stable ordering और explicit filter से शुरू होगा, यदि API इसका support करती हो:

GET /v1/integrations?status=inactive&updated_before=2024-01-01&limit=50&sort=id HTTP/1.1

Agent pages से IDs जुटाएगा और उन्हें बदलेगा नहीं। वह तभी रुकेगा जब server next cursor न दे या discovery budget लग जाए। फिर वह complete candidate set या partial candidate set report करेगा। अलग action request gathered IDs का इस्तेमाल कर सकती है, बेहतर होगा कि human पहले count और scope देख ले।

List endpoint stable ordering support न करती हो, तो agent को यह बताना चाहिए। वह candidates जुटा सकता है, लेकिन complete और race-free set का दावा नहीं करना चाहिए। «Items मिलते ही action लो» वाली लोकप्रिय सलाह efficient लगती है, क्योंकि इससे दूसरा pass बचता है। Mutable lists में यह गलत है, जब action sort position, eligibility या permissions बदल देता हो।

यही pattern security findings, user accounts, deployment records और build artifacts पर भी लागू होता है। पहले पढ़ें, scope तय करें, फिर बदलाव करें। Urgent containment में अपवाद हो सकते हैं, जैसे किसी स्पष्ट रूप से नामित compromised credential को revoke करना, लेकिन वह paginated cleanup job नहीं है। वह ज्ञात identifier के साथ targeted action है।

Credentials और observability agent से बाहर रखें

Agent को केवल paginate करने के लिए API secret की जरूरत नहीं होनी चाहिए। HTTP requests चलाने वाला component credentials डाल सकता है, जहाँ जरूरी हो वहाँ human authorization लागू कर सकता है और वास्तविक request sequence दर्ज कर सकता है। इससे agent query बनाने और उसका अर्थ समझने पर केंद्रित रहता है, न कि ऐसे tokens संभालने पर जिनसे वह कहीं और unbounded calls चला सके।

Sallyport इस्तेमाल करने वाली teams HTTP calls को उसके action gateway से चला सकती हैं, जबकि credentials encrypted vault में रहते हैं और Activity journal individual calls दर्ज करता है। यह record reviewer को agent के बताए page count की तुलना वास्तव में चली requests से करने में मदद करता है, लेकिन यह agent instructions में page budgets की जगह नहीं लेता।

Traversal policy को task definition के पास रखें। Allowed endpoints, filters, fields, maximum pages, retry behavior और required boundary statement स्पष्ट करें। General-purpose authorization layer यह तय नहीं कर सकती कि एक repository के scan के लिए एक page के बाद काम पूरा है या compliance inventory के लिए हर page चाहिए।

Sallyport का session journal और per-call activity trail तब revocation और review को व्यावहारिक बना सकता है जब agent run गलत दिशा में चला जाए। फिर भी agent को unrecognized cursor shape, exhausted budget या endpoint के documented contract से contradict करने वाले API response पर रुकने के लिए कहना होगा। खराब crawl को बाद में log करना कोई evidence न होने से बेहतर है, लेकिन इससे अनावश्यक calls या गलत action वापस नहीं होते।

Hostile pagination fixtures के खिलाफ traversal test करें

Happy-path pagination उन defects को छिपाती है जो सबसे ज्यादा मायने रखते हैं। Agent workflow पर भरोसा करने से पहले ऐसे fixtures के खिलाफ test करें जो cursor के साथ empty first page, more results वाला short page, duplicated item, repeated cursor, expired cursor और दो सामान्य pages के बीच rate-limit response लौटाएँ।

Expected behavior उबाऊ और स्पष्ट होना चाहिए। Agent empty page के बाद तभी आगे बढ़े जब documented continuation state आगे बढ़ने को कहे। Task की consistency requirement के अनुसार repeated IDs पर deduplicate करे या रुके। Expiry के बाद कभी cursor invent न करे और safety limit run खत्म करे तो partial coverage report करे।

Tool call loop की समीक्षा करते समय यह acceptance table इस्तेमाल करें:

Final prose के साथ raw calls भी inspect करें। Polished report skipped cursor या stop condition के बाद हुए extra request को छिपा सकती है। Execution log में एक initial request, हर continuation request, same cursor की कोई retry और terminal response के बाद कोई call न होना दिखना चाहिए।

Exploratory work के लिए छोटा default budget रखें और broad enumeration के लिए task में स्पष्ट बदलाव जरूरी करें। यह एक constraint उन दो failures को रोकती है जो सबसे ज्यादा समय बरबाद करती हैं: हमेशा scan करते रहने वाले agents और पहले page को चुपचाप पूरे answer समझ लेने वाले agents।