AI बिल्डर गाइड

Bird का API इंटरफ़ेस एजेंटों के लिए बना है: हर टूल के लिए एक ऑपरेशन, इनपुट और आउटपुट दोनों में JSON, और ऐसे परिणाम जिन्हें मशीन जाँच सके। फिर भी एक भरोसेमंद एजेंट के लिए सही पैटर्न ज़रूरी हैं। ये पाँच पैटर्न उन विफलताओं को कवर करते हैं जो एजेंट इंटीग्रेशन को तोड़ती हैं: स्वीकृति को डिलीवरी मान लेना, संदर्भ के बिना फिर से प्रयास करना, और संरचना के बजाय सामान्य टेक्स्ट को पार्स करना। हर पैटर्न एक जैसा काम करता है, चाहे आपका एजेंट MCP सर्वर चलाए या bird CLI। नीचे के उदाहरण ईमेल के हैं, क्योंकि भेजने से जुड़े टूल वहीं सबसे विस्तृत हैं। ये पैटर्न SMS और WhatsApp पर बिना बदलाव के लागू होते हैं: भेजते समय वही 202, स्वीकृति के बाद अंतिम स्थिति तक इवेंट का वही क्रम, और वही त्रुटि प्रतिक्रिया। एकमात्र अपवाद पैटर्न 3 है, जिसके मैजिक पते एक ईमेल सैंडबॉक्स हैं।

पैटर्न 1: लूप में एक बार में एक ऑपरेशन चलाएँ

Bird के टूल जानबूझकर छोटे-छोटे हैं: मैसेज भेजना, मैसेज प्राप्त करना, डोमेन की सूची देखना या वेबहुक एंडपॉइंट बनाना। हर टूल संरचित JSON लौटाता है, जिसके फ़ील्ड अगला चरण जाँच सकता है। लूप ऐसे बनाएँ कि हर चरण की समाप्ति की शर्त पिछले चरण के आउटपुट से तय हो:

loop:
  result = run_tool(next_operation)        # one operation per call
  if result.ok: advance using result.data  # for example, the em_… ID or verified domain
  else: branch on the failure category     # see Pattern 4

CLI में विफलता की श्रेणी ही एग्ज़िट कोड है, इसलिए ब्रांच करने के लिए मैसेज पार्स करने की ज़रूरत नहीं पड़ती। पूरी तालिका CLI में देखें:

bird email get "$id" --format json > msg.json
case $? in
  0) jq .status msg.json ;;     # advance
  3) echo "wrong ID: fix the value instead of retrying" ;;
  4) bird auth login ;;          # recover, then re-run
esac

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

पैटर्न 2: भेजने पर 202 मिलता है, परिणाम बाद में आता है

भेजने का अनुरोध POST करने पर आपको मैसेज ID के साथ 202 Accepted मिलता है। स्वीकृत का अर्थ है कि Bird ने मैसेज ले लिया है और डिलीवरी अभी बाकी है। अंतिम परिणाम वेबहुक इवेंट के रूप में आता है: प्राप्तकर्ता का सर्वर मैसेज स्वीकार करे तो email.delivered, डिलीवरी स्थायी रूप से विफल हो तो email.bounced, email.complained, इत्यादि।

जो एजेंट 202 पर ही सफलता घोषित कर देता है, उससे हर बाउंस चुपचाप छूट जाता है। इसलिए काम को भेजने और फिर परिणाम का इंतज़ार करने के रूप में बनाएँ:

send → 202 + em_… ID            # record the ID; delivery is still pending
await webhook event where data.email_id == em_… id:
  email.delivered → done
  email.bounced   → report failure with bounce_type / bounce_description

email_id के आधार पर मिलान करें। वेबहुक पेलोड पहचान फ़ील्ड के साथ आपके टैग और मेटाडेटा भी लौटाते हैं, इसलिए आपका अपना संदर्भ बिना अतिरिक्त लुकअप के वापस मिल जाता है। डिलीवरी कम से कम एक बार होती है और क्रम तय नहीं होता। webhook-id हेडर से डुप्लिकेट हटाएँ और पेलोड के timestamp से क्रम लगाएँ। अगर आपके एजेंट के पास वेबहुक रिसीवर नहीं है, तो स्थिति तय होने तक GET (या bird email get) से मैसेज को पोल करें। पोलिंग धीमी है, लेकिन वापस पढ़ा गया डेटा ही सही स्थिति का स्रोत रहता है।

पैटर्न 3: सैंडबॉक्स को अपने टेस्ट हार्नेस की तरह इस्तेमाल करें

लूप विकसित करते समय असली मेलबॉक्स की जगह messagebird.dev पर मेल सैंडबॉक्स के मैजिक पतों का इस्तेमाल करें। पता ही परिणाम तय करता है (delivered@ हमेशा डिलीवर होता है, bounce@ हमेशा हार्ड-बाउंस होता है, और complaint@ हमेशा शिकायत दर्ज करता है)। बाकी सब कुछ प्रोडक्शन पाइपलाइन से चलता है: वही 202, वही इवेंट क्रम और वही साइन किए गए वेबहुक डिलीवरी, और संदेश को टेस्ट के रूप में चिह्नित करने वाला कोई फ़्लैग नहीं होता।

for address in [delivered@, bounce@, suppressed@] @messagebird.dev:
  send to address+run42@…                  # +label correlates the test case
  assert the expected terminal event arrives (delivered / bounced / rejected)

सैंडबॉक्स निश्चित परिणाम देता है, प्रतिष्ठा को कोई जोखिम नहीं होता, सप्रेशन सूची में कुछ नहीं लिखा जाता, और पते हर रन में दोबारा इस्तेमाल हो सकते हैं। जो एजेंट सैंडबॉक्स मैट्रिक्स पास कर लेता है, वह किसी असली इनबॉक्स तक पहुँचने से पहले ही पैटर्न 2 का पूरा रास्ता (भेजना, इंतज़ार करना और ब्रांच करना) चला चुका होता है।

पैटर्न 4: मानक त्रुटि प्रतिक्रिया के आधार पर रिकवर करें

हर Bird API त्रुटि का आकार एक जैसा होता है, इसलिए त्रुटि से रिकवरी का एक ही रास्ता सभी एंडपॉइंट पर काम करता है:

{
  "error": {
    "type": "validation_error",
    "code": "E04006",
    "name": "DomainNotVerified",
    "message": "The from address uses a domain that is not verified in this workspace.",
    "doc_url": "https://bird.com/docs/api/errors/E04006",
    "request_id": "req_01krdgeqcxet5s7t44vh8rt9mg"
  }
}

लूप में हर फ़ील्ड का एक काम है। type/code पर ब्रांच करें (स्थिर और मशीन-पठनीय), message इंसान को दिखाएँ, और जब एजेंट को उसी त्रुटि का पेज चाहिए तो doc_url फ़ेच करें। यह URL ऐसे Markdown पर खुलता है जिसे एजेंट पढ़ सकता है। request_id लॉग करें ताकि कोई इंसान उसे Bird सपोर्ट को दे सके। फिर उन त्रुटियों को, जिनके लिए फिर से प्रयास किया जा सकता है, अनुरोध की त्रुटियों से अलग करें:

4xx (except 429) → a request bug: fix the input, never retry as-is
429              → back off, then retry (Pattern 5)
5xx / timeout    → retry with the same Idempotency-Key (Pattern 5)

पूरा कोड कैटलॉग त्रुटियों वाले पेज पर है। CLI के साथ त्रुटि प्रतिक्रिया stderr पर आती है और एग्ज़िट कोड उसे पहले से वर्गीकृत कर देता है (पैटर्न 1 और CLI में पूरी तालिका देखें)। इसलिए शेल चलाने वाला एजेंट कुछ भी पार्स करने से पहले ब्रांच कर सकता है।

पैटर्न 5: Idempotency-Key और Retry-After के साथ सुरक्षित रूप से फिर से प्रयास करें

जब कोई भेजने का अनुरोध टाइम आउट हो जाता है और एजेंट फिर से प्रयास करता है, तो काम दोहराया जा सकता है। Bird का idempotency सपोर्ट फिर से प्रयास को सुरक्षित बनाता है। हर तार्किक ऑपरेशन के लिए एक Idempotency-Key बनाएँ और हर प्रयास में उसी का दोबारा इस्तेमाल करें:

key = uuid()                                  # once per logical send
attempt with Idempotency-Key: key
on 5xx / timeout: backoff, retry with SAME key
on 2xx with Idempotency-Replay: true → the first attempt had succeeded; do not treat as a new send

Idempotency-Replay: true रिस्पॉन्स हेडर बताता है कि यह मूल रिस्पॉन्स का रीप्ले है, ताकि आपका एजेंट "sent twice" की जगह "recovered" लॉग कर सके। Bird SDK हर बदलाव करने वाले अनुरोध पर अपने आप एक कुंजी जोड़ते हैं, इसलिए SDK पर आधारित एजेंट को यह बिना किसी अतिरिक्त काम के मिलता है; CLI के साथ, उन बदलावों पर --idempotency-key पास करें जिनके लिए फिर से प्रयास हो सकता है।

429 का मतलब है कि एजेंट को धीमा होना होगा। रिस्पॉन्स में Retry-After हेडर होता है; अलग शेड्यूल बनाने के बजाय इसे न्यूनतम बैकऑफ़ के रूप में इस्तेमाल करें:

on 429: sleep max(Retry-After, backoff(attempt)); retry with the same key

दूसरे 4xx रिस्पॉन्स के लिए बिना बदलाव के फिर से प्रयास न करें। Idempotency उन्हें कैश करके रीप्ले करती है, क्योंकि वही अनुरोध वही त्रुटि देता है। अनुरोध ठीक करें (पैटर्न 4) और नई कुंजी इस्तेमाल करें; किसी कुंजी को अलग बॉडी के साथ दोबारा इस्तेमाल करने पर 409 IdempotencyKeyReuse मिलता है।

अगले कदम

• MCP सर्वर: वह टूल सतह जिसे ये पैटर्न चलाते हैं, mcp.bird.com पर होस्ट की गई या CLI के साथ लोकल रूप से चलाई गई
• एजेंट के लिए CLI: शेल चला सकने वाले एजेंट के लिए वही ऑपरेशन
• वेबहुक और इवेंट: डिलीवरी का व्यवहार, सिग्नेचर और पैटर्न 2 के पीछे का इवेंट कैटलॉग
• आइडेम्पोटेंसी: पैटर्न 5 के पीछे का रीप्ले व्यवहार और विफलता के तरीके
• त्रुटियाँ: त्रुटि प्रतिक्रिया और पूरा त्रुटि-कोड कैटलॉग
• मेल सैंडबॉक्स: पैटर्न 3 के पीछे का मैजिक-पता मैट्रिक्स