Panduan AI builder

Permukaan API Bird berbentuk agen: satu operasi per tool, JSON masuk dan keluar, dan hasil yang dapat diperiksa mesin. Agen yang andal tetap memerlukan pola yang tepat di sekelilingnya. Lima pola ini mencakup mode kegagalan yang merusak integrasi agen: menganggap penerimaan sebagai pengiriman, retry tanpa konteks, dan mem-parsing prosa alih-alih struktur. Setiap pola bekerja sama baik agen Anda menggerakkan MCP server maupun bird CLI. Contoh di bawah ini adalah email, karena di situlah tooling seputar pengiriman paling mendalam, dan polanya berlaku untuk SMS dan WhatsApp tanpa perubahan: 202 yang sama pada pengiriman, urutan event accepted-then-terminal yang sama, envelope error yang sama. Satu-satunya pengecualian adalah Pola 3, yang alamat ajaibnya merupakan sandbox email.

Pola 1: Loop satu operasi pada satu waktu

Tool Bird sengaja dibuat granular: kirim pesan, ambil pesan, daftar domain, atau buat endpoint webhook. Setiap tool mengembalikan JSON terstruktur yang field-nya dapat diperiksa oleh langkah berikutnya. Bangun loop sehingga kondisi keluar setiap langkah berasal dari output langkah sebelumnya:

Contoh kode

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

Dengan CLI, kategori kegagalan adalah exit code, sehingga percabangan tidak memerlukan parsing pesan. Lihat tabel lengkap di CLI:

Contoh kode

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

Granularitas inilah intinya: agen yang dapat memeriksa state di antara langkah-langkah dapat pulih dari kegagalan tunggal mana pun; agen yang menjalankan satu mega-operasi hanya bisa memulai dari awal.

Pola 2: Pengiriman mengembalikan 202; hasilnya tiba kemudian

POST pengiriman dan Anda mendapat 202 Accepted dengan message ID. Accepted berarti Bird menerima pesan dan pengiriman sedang pending. Hasil akhir tiba sebagai event webhook: email.delivered ketika server penerima menerimanya, email.bounced ketika pengiriman gagal secara permanen, email.complained, dan seterusnya.

Agen yang menyatakan sukses pada 202 diam-diam melewatkan setiap bounce. Strukturkan tugas sebagai kirim-lalu-tunggu:

Contoh kode

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

Korelasikan pada email_id. Payload webhook menyertakan tag dan metadata Anda bersama field identitas, sehingga konteks Anda sendiri kembali tanpa lookup tambahan. Pengiriman bersifat at-least-once dan tidak berurutan; deduplikasi pada header webhook-id dan urutkan berdasarkan timestamp payload. Jika agen Anda tidak memiliki penerima webhook, poll pesan dengan GET (atau bird email get) hingga statusnya terselesaikan. Polling lebih lambat, tetapi pembacaan ulang tetap menjadi sumber kebenaran.

Pola 3: Gunakan sandbox sebagai harness pengujian Anda

Saat mengembangkan loop, gunakan alamat ajaib mail sandbox di messagebird.dev alih-alih mailbox nyata. Alamat menentukan hasilnya (delivered@ selalu terkirim, bounce@ selalu hard-bounce, dan complaint@ selalu komplain). Yang lainnya menggunakan pipeline produksi: 202 yang sama, urutan event, dan pengiriman webhook bertanda tangan yang sama, tanpa flag yang menandai pesan sebagai tes.

Contoh kode

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 menyediakan hasil deterministik, nol risiko reputasi, tidak ada penulisan suppression-list, dan alamat yang dapat digunakan ulang di setiap run. Agen yang lolos matriks sandbox telah menjalankan jalur Pola 2 yang lengkap (kirim, tunggu, dan cabang) sebelum menyentuh inbox nyata.

Pola 4: Pulihkan terhadap envelope error standar

Setiap error API Bird memiliki bentuk yang sama, sehingga satu jalur pemulihan error bekerja di semua endpoint:

Contoh kode

{
  "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"
  }
}

Setiap field memiliki tugas dalam loop. Cabangkan pada type/code (stabil dan dapat dibaca mesin), tampilkan message kepada manusia, dan ambil doc_url ketika agen membutuhkan halaman untuk error tersebut. URL di-resolve ke Markdown yang dapat dibaca agen. Log request_id agar manusia dapat menyerahkannya ke dukungan Bird. Kemudian pisahkan error yang retryable dari error request:

Contoh kode

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)

Katalog kode lengkap ada di halaman error. Dengan CLI, envelope tiba di stderr dan exit code sudah mengklasifikasikannya (lihat Pola 1 dan tabel lengkap di CLI). Agen yang menggerakkan shell karenanya dapat bercabang sebelum mem-parsing apa pun.

Pola 5: Retry dengan aman menggunakan Idempotency-Key dan Retry-After

Retry dapat menduplikasi pekerjaan ketika pengiriman timeout dan agen mencoba lagi. Dukungan idempotency Bird membuat retry aman. Hasilkan satu Idempotency-Key per operasi logis dan gunakan ulang pada setiap percobaan:

Contoh kode

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

Header respons Idempotency-Replay: true menandai replay dari respons asli, sehingga agen Anda dapat mencatat "recovered" alih-alih "sent twice". SDK Bird menyuntikkan key secara otomatis pada setiap request yang bermutasi, sehingga agen berbasis SDK mendapatkan ini secara gratis; dengan CLI, berikan --idempotency-key pada mutasi yang mungkin di-retry.

429 berarti agen harus melambat. Respons membawa header Retry-After; gunakan sebagai backoff minimum alih-alih membuat jadwal terpisah:

Contoh kode

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

Jangan retry respons 4xx lainnya tanpa perubahan. Idempotency meng-cache dan me-replay-nya karena request yang sama menghasilkan error yang sama. Perbaiki request (Pola 4) dan gunakan key baru; menggunakan ulang key dengan body berbeda mengembalikan 409 IdempotencyKeyReuse.

Langkah selanjutnya

MCP server: permukaan tool yang digerakkan oleh pola-pola ini, di-host di mcp.bird.com atau dijalankan secara lokal dengan CLI
CLI untuk agen: operasi yang sama untuk agen berkemampuan shell
Webhook & event: semantik pengiriman, tanda tangan, dan katalog event di balik Pola 2
Idempotency: semantik replay dan mode kegagalan di balik Pola 5
Error: envelope dan katalog kode error lengkap
Mail sandbox: matriks alamat ajaib di balik Pola 3