Panduan AI builder

Permukaan API Bird dirancang untuk agen: satu operasi per alat, JSON masuk dan keluar, serta hasil yang dapat diperiksa mesin. Agen yang andal tetap membutuhkan pola yang tepat di sekitarnya. Lima pola ini mencakup mode kegagalan yang merusak integrasi agen: memperlakukan penerimaan sebagai pengiriman, mencoba ulang tanpa konteks, dan mengurai prosa alih-alih struktur. Setiap pola bekerja sama baik agen Anda menggunakan server MCP maupun bird CLI. Contoh di bawah menggunakan email, karena di situlah perkakas di sekitar pengiriman paling lengkap, dan polanya berlaku untuk SMS dan WhatsApp tanpa perubahan: 202 yang sama pada pengiriman, urutan event accepted-then-terminal yang sama, respons kesalahan yang sama. Satu-satunya pengecualian adalah Pola 3, yang alamat ajaibnya khusus untuk sandbox email.

Pola 1: Jalankan satu operasi per langkah

Alat-alat Bird sengaja dibuat granular: kirim pesan, ambil pesan, daftar domain, atau buat endpoint webhook. Setiap alat mengembalikan JSON terstruktur yang field-nya dapat diperiksa 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 perlu mengurai 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 masih tertunda. Hasil akhir tiba sebagai event webhook: email.delivered ketika server penerima menerimanya, email.bounced ketika pengiriman gagal permanen, email.complained, dan seterusnya.

Agen yang menyatakan sukses pada 202 diam-diam melewatkan setiap bounce. Strukturkan tugas sebagai send-then-await:

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 mengembalikan tag dan metadata Anda bersama field identitas, sehingga konteks Anda kembali tanpa pencarian tambahan. Pengiriman bersifat at-least-once dan tidak berurutan; deduplikasi pada header webhook-id dan urutkan berdasarkan timestamp payload. Jika agen Anda tidak memiliki receiver webhook, polling pesan dengan GET (atau bird email get) sampai statusnya terselesaikan. Polling lebih lambat, tetapi pembacaan ulang tetap menjadi sumber kebenaran.

Pola 3: Gunakan sandbox sebagai test harness Anda

Selama mengembangkan loop, gunakan alamat ajaib mail sandbox pada messagebird.dev alih-alih kotak surat asli. Alamat menentukan hasilnya (delivered@ selalu terkirim, bounce@ selalu hard-bounce, dan complaint@ selalu komplain). Semua lainnya menggunakan pipeline produksi: 202 yang sama, urutan event, dan pengiriman webhook bertanda tangan, 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, tanpa penulisan ke suppression list, dan alamat yang dapat digunakan ulang lintas percobaan. Agen yang lulus matriks sandbox telah menjalankan jalur Pola 2 secara lengkap (kirim, tunggu, dan percabangan) sebelum menyentuh inbox asli.

Pola 4: Pulihkan menggunakan respons kesalahan standar

Setiap kesalahan API Bird memiliki bentuk yang sama, sehingga satu jalur pemulihan kesalahan berlaku 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 peran dalam loop. Percabangan berdasarkan type/code (stabil dan dapat dibaca mesin), tampilkan message kepada manusia, dan ambil doc_url ketika agen membutuhkan halaman untuk kesalahan tersebut. URL mengarah ke Markdown yang dapat dibaca agen. Catat request_id agar manusia dapat memberikannya ke dukungan Bird. Kemudian pisahkan kesalahan yang dapat dicoba ulang dari kesalahan permintaan:

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 errors. Dengan CLI, envelope tiba di stderr dan exit code mengklasifikasikannya terlebih dahulu (lihat Pola 1 dan tabel lengkap di CLI). Agen berbasis shell dapat melakukan percabangan sebelum mengurai apa pun.

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

Percobaan ulang dapat menduplikasi pekerjaan ketika pengiriman timeout dan agen mencoba lagi. Dukungan idempotensi Bird membuat percobaan ulang aman. Buat satu Idempotency-Key per operasi logis dan gunakan kembali 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 permintaan mutasi, sehingga agen berbasis SDK mendapatkannya secara gratis; dengan CLI, berikan --idempotency-key pada mutasi yang mungkin dicoba ulang.

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 coba ulang respons 4xx lainnya tanpa perubahan. Idempotensi menyimpan cache dan memutar ulangnya karena permintaan yang sama menghasilkan kesalahan yang sama. Perbaiki permintaan (Pola 4) dan gunakan key baru; menggunakan ulang key dengan body berbeda mengembalikan 409 IdempotencyKeyReuse.

Langkah selanjutnya

Server MCP: permukaan alat yang digunakan pola-pola ini, di-host di mcp.bird.com atau dijalankan 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
Idempotensi: semantik replay dan mode kegagalan di balik Pola 5
Errors: envelope dan katalog kode kesalahan lengkap
Mail sandbox: matriks alamat ajaib di balik Pola 3

Sumber daya terkait

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.

Pahami konsepnyaHow do I use Bird from a low-code tool like n8n or Zapier?Jelajahi kemampuannyaWorkflow automation Ikuti jalur pembelajaranBuild with AI agents

Dapatkan ringkasan implementasi