Apa yang dapat dilakukan agen AI di Bird: CLI, MCP, pendaftaran dari terminal, dan kontrol pengeluaran

Pada bulan September kami mengumumkan bahwa infrastruktur komunikasi Bird terbuka untuk agen AI. Tulisan ini adalah versi pengumuman tersebut untuk developer. Tulisan ini menyebutkan perintah yang dijalankan agen, layanan yang dihubunginya, cara agen mendapatkan akun, dan batasan yang dapat Anda terapkan padanya, masing-masing dengan halaman dokumentasinya.

CLI

Agen yang dapat menjalankan perintah shell, seperti Claude Code, terminal Cursor, atau job CI, sebaiknya mulai dengan CLI: untuk setiap operasi, alat ini menggunakan token jauh lebih sedikit daripada MCP. Server MCP, yang dijelaskan berikutnya, ditujukan untuk host yang memanggil tool tetapi tidak dapat menjalankan shell, serta untuk MCP Events.

bird adalah satu binary yang dirancang untuk dikendalikan oleh agen. Output berupa JSON di stdout, error dikirim ke stderr, dan exit code menunjukkan kategori kegagalan, sehingga agen dapat mengambil keputusan berdasarkan hasilnya tanpa mengurai teks.

curl -fsSL https://cli.bird.com/install.sh | sh
bird auth login

Tiga flag melakukan sebagian besar pekerjaan untuk agen. --example mencetak body permintaan yang valid, --dry-run menampilkan permintaan tanpa mengirimkannya, dan --idempotency-key membuat percobaan ulang aman saat respons hilang. CLI untuk agen menjelaskan kontraknya, dan referensi CLI mencantumkan setiap perintah.

Server MCP yang di-hosting

Beberapa host memanggil tool tetapi tidak dapat menjalankan shell, seperti Claude Desktop, ChatGPT, atau aplikasi seluler. Untuk host tersebut, server Bird MCP berjalan di https://mcp.bird.com. Berikan URL tersebut ke klien MCP lalu masuk melalui browser Anda, dan klien akan menyimpan token yang bertindak atas nama Anda. Layar persetujuan menampilkan izin yang diminta klien, dan Anda dapat menghapus centang izin yang tidak diperlukan agen. Anda tidak perlu menginstal apa pun atau menyalin kunci API. Klien yang didukung antara lain Claude Code, Cursor, VS Code, Codex, Claude, ChatGPT, dan Muse, dan Bird tercantum di direktori konektor Claude.

Server ini menyediakan Bird API sebagai tool, sehingga agen yang terhubung dapat mengirim pesan melalui kanal yang dijalankan Bird, menyiapkan kanal tersebut, dan memeriksa workspace Anda. Klien yang membatasi jumlah tool dapat terhubung ke https://mcp.bird.com/dynamic, yang hanya menyediakan dua tool: search untuk menemukan operasi dan execute untuk memanggilnya. Dengan MCP Events, klien berlangganan peristiwa di workspace Anda, seperti SMS masuk atau email baru di kotak surat, sehingga agen tidak perlu melakukan polling.

Server MCP berisi langkah-langkah untuk setiap klien. Setelah CLI terinstal, bird mcp menjalankan server lokal melalui stdio. Server lokal ini menambahkan tool pendaftaran dan unggahan dari file lokal, tetapi tidak menyediakan MCP Events.

Pendaftaran dari terminal

Agen yang belum memiliki akun dapat membuatnya dari terminal, tanpa sesi browser dan tanpa membuka dashboard. Agen memerlukan akses ke kotak masuk email, karena kode masuk dikirim melalui email:

bird auth signup you@example.com
bird auth verify-email you@example.com --code 123456
bird auth create-org "Acme" --workspace-name "Production" --region eu1 --onboarding-ticket "YOUR_ONBOARDING_TICKET"

bird auth create-org membuat organisasi beserta workspace-nya, lalu menyimpan kredensial yang selanjutnya digunakan oleh CLI dan server MCP lokal. --region menentukan lokasi akun dan datanya, us1 atau eu1. Tiga langkah yang sama juga dapat dijalankan dengan curl, untuk agen yang tidak memiliki CLI. Server MCP yang di-hosting tidak menyediakan pendaftaran, karena klien memerlukan kredensial sebelum dapat terhubung ke sana.

Kredensial pertama itu memiliki cakupan luas. Kredensial ini memegang izin yang dapat didelegasikan oleh pemilik organisasi baru, termasuk penagihan organisasi, dan pendaftaran tidak menampilkan layar persetujuan untuk mempersempitnya. Sebelum agen berjalan tanpa pengawasan, buat kunci API dengan cakupan terbatas untuknya. Pendaftaran mandiri menjelaskan kedua cara tersebut.

Kontrol atas tindakan agen

Agen yang mengirim melalui Bird memegang kredensial dan menggunakan saldo Anda. Kontrol agen mendokumentasikan dalam satu halaman hal-hal yang membatasinya. Berikut empat kontrol yang perlu Anda atur sebelum agen berjalan tanpa pengawasan. Daftar izin tujuan dan batas pengeluaran harian berlaku untuk SMS. Email dan WhatsApp tidak memiliki keduanya, sehingga di sana agen dibatasi oleh cakupan kunci dan dompet. Halaman yang sama juga membahas percobaan ulang yang aman: kirim header Idempotency-Key, atau --idempotency-key pada CLI, dan permintaan yang diulang hanya diterima sekali.

Kunci API dengan cakupan terbatas. Kunci API dimiliki oleh satu workspace dan membawa cakupan yang Anda berikan, masing-masing berupa area produk pada tingkat read atau write. Kunci yang hanya mengirim SMS memegang sms:write, dan permintaan di luar cakupannya menghasilkan 403. Kunci tidak dapat menerbitkan kunci lain dan tidak dapat mengakses penagihan.

bird auth login --scope api_keys:write --scope sms:write   # an existing account
bird api-keys create --name "Support agent" --scope sms:write

Sesi masuk harus memegang api_keys:write dan cakupan yang akan dibawa kunci. Kredensial dari pendaftaran terminal sudah memegangnya, sehingga setelah bird auth create-org Anda cukup menjalankan perintah kedua. Jangan masuk lagi di sana: sesi masuk baru akan menggantikan kredensial pendaftaran. Jalankan perintah itu di shell yang tidak menetapkan BIRD_API_KEY, karena CLI lebih mengutamakan kunci tersebut daripada sesi masuk, dan kunci tidak dapat menerbitkan kunci.

Setelah itu, berikan kunci tersebut kepada agen dan jangan berikan akses yang lebih luas. Tetapkan BIRD_API_KEY di lingkungan agen, atau kirim kunci sebagai bearer token dari kode Anda. Sesi masuk tetap tersimpan di mesin tempat sesi itu dijalankan, dan agen di mesin tersebut yang tidak memiliki BIRD_API_KEY akan menggunakannya. Jalankan agen di tempat lain, atau hapus sesi masuk dengan bird auth logout.

Tujuan SMS yang ditolak secara default. Workspace mengirim SMS ke negara-negara yang ada di daftar izin tujuannya. Daftar izin awalnya kosong, dan Bird menambahkan negara asal organisasi Anda jika sudah ditetapkan. Pengiriman melalui SMS API ke negara lain ditolak dengan 422 SMSDestinationNotEnabled sebelum pengirim ditentukan, sehingga agen yang diarahkan ke negara tak terduga akan ditolak. Kode verifikasi tidak menggunakan daftar ini. Verify memiliki daftarnya sendiri, dengan semua negara aktif sejak awal, dan Voice juga memiliki pengaturannya sendiri.

Batas pengeluaran harian. Setiap negara tujuan SMS dapat diberi batas pengeluaran harian, dalam mata uang dompet Anda. Begitu pengeluaran hari itu ke negara tersebut mencapai batas, Bird menolak pesan baru ke sana hingga tengah malam UTC. Batas ini tidak presisi: pengeluaran dihitung saat pesan ditagih, sehingga pesan yang sudah diterima dapat membuat total hari itu melampauinya. Kode verifikasi yang dikirim oleh SMS ikut dihitung dalam batas. Perintah ini mengaktifkan Belanda dengan batas 25 EUR per hari, di workspace yang dompetnya dalam EUR:

bird sms destinations update --destination "NL=true;25EUR"

Untuk mengubah daftar izin atau batas, diperlukan cakupan sms_management pada tingkat write. Berikan sms kepada agen pengirim, simpan sms_management untuk kredensial yang mengonfigurasi workspace, dan agen tidak akan dapat menaikkan batasnya sendiri.

Dompet prabayar. Pengiriman bayar sesuai pemakaian mengambil saldo dari dompet prabayar organisasi Anda. Pengiriman SMS yang tidak dapat ditanggung saldo akan ditolak dengan 402. Sebagian biaya diselesaikan setelah pengiriman diterima (email pada paket Email berbayar, dan biaya yang dikenakan saat pengiriman), dan isi ulang otomatis mengisi dompet dari kartu yang tersimpan. Karena itu, baca aturan dompet sebelum Anda menganggap saldo sebagai batas mutlak. Operasi penagihan memerlukan izin penagihan organisasi, yang tidak dapat dimiliki kunci API. Berikan kunci dengan cakupan terbatas kepada agen yang berjalan tanpa pengawasan, sehingga penambahan dana tetap berada di tangan orang yang memegang anggaran.

Langkah selanjutnya

Start building with Bird in minutes.