AI बिल्डर गाइड

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

Pattern 1: एक बार में एक ऑपरेशन लूप करें

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

कोड उदाहरण

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 के साथ, विफलता की श्रेणी exit code होती है, इसलिए ब्रांच को कोई संदेश पार्सिंग नहीं चाहिए। पूरी तालिका 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

बारीकी ही मुख्य बात है: एक एजेंट जो कदमों के बीच स्थिति जाँच सकता है, किसी भी एकल विफलता से उबर सकता है; एक mega-operation चलाने वाला एजेंट केवल शुरू से दोबारा शुरू कर सकता है।

Pattern 2: एक send 202 लौटाता है; परिणाम बाद में आता है

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

एक एजेंट जो 202 पर सफलता घोषित करता है, हर bounce को चुपचाप चूक जाता है। कार्य को send-then-await के रूप में संरचित करें:

कोड उदाहरण

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 पेलोड आपके tags और metadata को identity फ़ील्ड के साथ echo करते हैं, इसलिए आपका अपना संदर्भ बिना अतिरिक्त lookup के वापस आ जाता है। डिलीवरी at-least-once और अक्रमित होती हैं; webhook-id हेडर पर डिडुप्लिकेट करें और पेलोड timestamp पर सॉर्ट करें। अगर आपके एजेंट के पास webhook receiver नहीं है, तो GET (या bird email get) से संदेश को पोल करें जब तक उसकी स्थिति resolved न हो जाए। पोलिंग धीमी है, लेकिन read-back ही सत्य का स्रोत रहता है।

Pattern 3: sandbox को अपने टेस्ट हार्नेस के रूप में उपयोग करें

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

कोड उदाहरण

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)

Sandbox नियतात्मक परिणाम, शून्य प्रतिष्ठा जोखिम, कोई suppression-list राइट नहीं, और रन के बीच पुन: उपयोग योग्य addresses प्रदान करता है। एक एजेंट जो sandbox मैट्रिक्स पास करता है, उसने किसी असली inbox को छूने से पहले पूरा Pattern 2 पथ (send, await, और branch) अभ्यास कर लिया है।

Pattern 4: मानक त्रुटि प्रतिक्रिया के अनुसार रिकवर करें

हर Bird API त्रुटि की संरचना एक जैसी होती है, इसलिए एक त्रुटि-रिकवरी पथ सभी endpoints पर काम करता है:

कोड उदाहरण

{
  "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 में resolve होता है जिसे एजेंट पढ़ सकता है। request_id लॉग करें ताकि कोई व्यक्ति इसे Bird सपोर्ट को दे सके। फिर फिर से प्रयास योग्य त्रुटियों को request त्रुटियों से अलग करें:

कोड उदाहरण

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)

पूरा कोड कैटलॉग errors पेज पर है। CLI के साथ, envelope stderr पर आता है और exit code इसे पहले से वर्गीकृत कर देता है (Pattern 1 और पूरी तालिका CLI में देखें)। इसलिए shell-driving एजेंट कुछ भी पार्स करने से पहले ब्रांच कर सकता है।

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

जब एक send टाइम आउट होता है और एजेंट दोबारा प्रयास करता है, तो फिर से प्रयास काम डुप्लिकेट कर सकते हैं। Bird का idempotency सपोर्ट फिर से प्रयास को सुरक्षित बनाता है। प्रति logical operation एक 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 response हेडर मूल response के replay को चिह्नित करता है, इसलिए आपका एजेंट "sent twice" की जगह "recovered" लॉग कर सकता है। Bird SDK हर mutating request पर स्वचालित रूप से एक key इंजेक्ट करते हैं, इसलिए SDK-आधारित एजेंट यह मुफ़्त में पाते हैं; CLI के साथ, उन mutations पर --idempotency-key पास करें जिन्हें फिर से प्रयास किया जा सकता है।

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

कोड उदाहरण

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

अन्य 4xx responses को बिना बदले फिर से प्रयास न करें। Idempotency उन्हें कैश और रीप्ले करती है क्योंकि वही request वही त्रुटि उत्पन्न करता है। Request ठीक करें (Pattern 4) और एक नई key उपयोग करें; अलग body के साथ key दोबारा उपयोग करने पर 409 IdempotencyKeyReuse मिलता है।

अगले कदम

MCP server: वह टूल सतह जिसे ये पैटर्न चलाते हैं, mcp.bird.com पर होस्ट किया गया या CLI के साथ लोकली चलाएँ
एजेंट के लिए CLI: shell-capable एजेंट के लिए वही ऑपरेशन
Webhooks और इवेंट: Pattern 2 के पीछे डिलीवरी सेमेंटिक्स, signatures, और इवेंट कैटलॉग
Idempotency: Pattern 5 के पीछे replay सेमेंटिक्स और विफलता मोड
Errors: envelope और पूरा error-code कैटलॉग
Mail sandbox: Pattern 3 के पीछे magic-address मैट्रिक्स

AI बिल्डर गाइड

Pattern 1: एक बार में एक ऑपरेशन लूप करें

Pattern 2: एक send 202 लौटाता है; परिणाम बाद में आता है

Pattern 3: sandbox को अपने टेस्ट हार्नेस के रूप में उपयोग करें

Pattern 4: मानक त्रुटि प्रतिक्रिया के अनुसार रिकवर करें

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

अगले कदम

संबंधित संसाधन