---
title: "Kontrol agen: kunci dengan cakupan terbatas, batas pengeluaran, dan coba lagi yang aman"
description: "Cara Bird membatasi apa yang dapat dilakukan agen AI: kunci API dengan cakupan terbatas, pengiriman idempoten, tujuan SMS yang ditolak secara default, batas pengeluaran harian per negara, dan dompet prabayar."
canonical: "https://bird.com/id-id/dokumentasi/ai/agent-controls"
---

# Kontrol agen: kunci dengan cakupan terbatas, batas pengeluaran, dan coba lagi yang aman

Agen yang mengirim melalui Bird memegang kredensial dan menggunakan saldo Anda. Lima kontrol membatasi apa yang dapat dilakukannya. Kontrol pertama adalah kredensial itu sendiri. Empat kontrol lainnya hanya berlaku selama kredensial agen tidak dapat mengubahnya, jadi mulailah dari kredensial.

| Kontrol                                                                            | Yang dibatasi                                    | Yang diterima pemanggil saat mencapai batas                           | Yang menetapkannya                                    |
| ---------------------------------------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------- | ----------------------------------------------------- |
| [Kredensial](#pilih-kredensial-yang-dipegang-agen)                                 | Operasi yang dapat dipanggil agen                | `403`                                                                 | Orang yang membuat kunci atau menyetujui proses masuk |
| [Kunci idempotensi](#coba-lagi-pengiriman-tanpa-mengirim-dua-kali)                 | Pengiriman ganda saat permintaan dicoba lagi     | Respons asli, diputar ulang                                           | Pemanggil, pada setiap permintaan                     |
| [Daftar izin tujuan SMS](#izinkan-setiap-negara-tujuan-sms)                        | Negara yang dapat dituju oleh pengiriman SMS API | `422 SMSDestinationNotEnabled`                                        | Kredensial dengan akses tulis `sms_management`        |
| [Batas pengeluaran harian SMS](#batasi-pengeluaran-harian-sms-untuk-setiap-negara) | Pengeluaran SMS ke satu negara dalam sehari      | `422 SMSDestinationDailySpendExceeded`                                | Kredensial dengan akses tulis `sms_management`        |
| [Dompet prabayar](#batasi-total-pengeluaran-dengan-dompet-prabayar)                | Pengeluaran bayar sesuai pemakaian               | `402` untuk SMS dan WhatsApp. Email berbayar ditagih setelah dikirim. | Pemilik organisasi atau admin penagihan               |

Daftar izin tujuan dan batas pengeluaran harian di halaman ini berlaku untuk SMS. [Verify](/docs/guides/verify/destinations) dan [Voice](/docs/guides/voice/destinations) masing-masing memiliki pengaturan tujuan sendiri, dengan kondisi awal yang berbeda. Email dan WhatsApp tidak memiliki daftar izin tujuan maupun batas pengeluaran harian, sehingga di sana agen hanya dibatasi oleh cakupan kredensial dan dompet.

## Pilih kredensial yang dipegang agen

Agen memanggil Bird dengan salah satu dari dua jenis kredensial. Keduanya berbeda dalam jangkauan aksesnya.

- **Kunci API** (`bk_`) membawa cakupan yang Anda berikan dan terikat pada satu workspace. Kunci ini tidak dapat menerbitkan kunci lain, dan tidak dapat mengakses penagihan, anggota, atau pengaturan organisasi. Kode Anda mengirimkannya sebagai bearer token. CLI dan server MCP lokal (`bird mcp`) menggunakan kunci di `BIRD_API_KEY` jika diatur, alih-alih login yang tersimpan.
- **Token OAuth** (`bt_`) adalah kredensial yang dipegang CLI dan server MCP setelah seseorang login. Token ini membawa izin yang disetujui orang tersebut, dan tidak pernah melebihi izin yang dimilikinya. Izin itu dapat mencakup akses tulis `api_keys`, akses tulis `sms_management`, dan penagihan organisasi. Agen dengan token seperti itu dapat menerbitkan kunci, mengaktifkan negara, dan menaikkan batas di halaman ini.

Seberapa banyak yang dapat dilakukan token OAuth bergantung pada cara token itu dibuat:

- **`bird auth login`** meminta akses baca saja. `--scope` meminta kumpulan izin yang Anda sebutkan, dan `--yolo` meminta semua izin yang dapat Anda delegasikan. Anda menyetujui hasilnya di browser.
- **Klien MCP yang di-hosting** dapat meminta semua izin yang dapat Anda delegasikan. Layar persetujuan memungkinkan Anda memilih izin yang akan diberikan. Hapus centang izin yang tidak dibutuhkan agen sebelum Anda menyetujui.
- **[Self-serve signup](/docs/ai/self-serve-signup)** tidak memiliki layar persetujuan. Kredensial yang dibuatnya memegang setiap izin yang dapat didelegasikan oleh pemilik organisasi baru, termasuk penagihan organisasi.

Untuk agen yang berjalan tanpa pengawasan, buat kunci API dengan cakupan terbatas dan berikan kunci itu kepada agen. Simpan sign-in yang lebih luas untuk orang yang mengonfigurasi workspace. Anda dapat mencabut sign-in sebuah alat di **Profile** > [**Connected apps**](https://bird.com/dashboard/profile/connected-apps). [Kunci API dan token OAuth](/explained/platform/api-key-or-oauth-token-and-how-do-i-rotate-one) membandingkan kedua jenis kredensial tersebut.

## Batasi cakupan setiap kunci pada produk yang dibutuhkannya

Kunci API membawa daftar cakupan, masing-masing berupa area produk pada tingkat `read` atau `write`. Kunci yang hanya mengirim SMS memegang `sms:write`. Permintaan di luar cakupan kunci menghasilkan `403`, sehingga kunci yang bocor atau disalahgunakan hanya menjangkau apa yang Anda berikan.

Tiga sifat kunci berlaku apa pun cakupannya:

- **Kunci tidak dapat menerbitkan kunci lain.** Menerbitkan dan merotasi kunci memerlukan `api_keys:write`, yang tidak tersedia untuk kunci API. Seseorang menyetujuinya melalui sesi dashboard atau melalui sign-in CLI atau MCP.
- **Kunci terbatas pada workspace-nya.** Kunci tidak dapat menjangkau penagihan, anggota organisasi, atau pengaturan organisasi.
- **Kunci dapat kedaluwarsa.** Atur `expires_at` saat Anda membuatnya, dan kunci akan menghasilkan `401` setelah waktu tersebut. Rotasi atau cabut kunci kapan saja.

Buat kunci di dashboard atau dari terminal. Sign-in CLI hanya dapat memberikan cakupan yang dimilikinya sendiri kepada kunci, sehingga sign-in ini meminta `sms:write` selain `api_keys:write`:

```bash
bird auth login --scope api_keys:write --scope sms:write
bird api-keys create --name "Support agent" --scope sms:write
```

[Autentikasi & kunci API](/docs/guides/authentication) berisi tabel cakupan serta membahas kedaluwarsa, rotasi, dan pencabutan.

## Coba lagi pengiriman tanpa mengirim dua kali

Agen yang kehilangan respons tidak dapat mengetahui apakah permintaannya diterima. Kirim header `Idempotency-Key` dengan nilai unik untuk setiap pengiriman yang dimaksud, dan ulangi permintaan yang sama dengan kunci yang sama saat hasilnya tidak diketahui. Bird mengembalikan respons asli dan menerima pesan hanya sekali. Respons yang diputar ulang membawa `Idempotency-Replay: true`.

Jaminannya adalah satu operasi yang diterima per kunci selama jendela retensi. Jaminan ini mencakup penerimaan oleh API. Pengiriman ke ponsel dilaporkan terpisah, melalui status pesan dan event-nya.

SDK membuat kunci untuk setiap panggilan yang mengubah data dan menggunakannya kembali untuk percobaan ulang otomatisnya. Di CLI, berikan `--idempotency-key`. [Idempotency](/docs/guides/idempotency) membahas format kunci, jendela retensi, dan apa yang terjadi jika kunci digunakan kembali untuk permintaan yang berbeda.

## Izinkan setiap negara tujuan SMS

Allowlist tujuan SMS menolak secara default. Pengiriman melalui SMS API hanya diteruskan ke negara yang diaktifkan dalam daftar. Jika tidak, pengiriman ditolak dengan `422 SMSDestinationNotEnabled` sebelum pengirim ditentukan, sehingga tidak ada pesan yang diterima. Agen yang diarahkan ke negara yang tidak terduga akan ditolak. Ini berlaku untuk pengiriman dari kode Anda sendiri, dari `bird sms send`, dan dari tool MCP `sms_send`.

Kode verifikasi tidak menggunakan daftar ini. Verify memiliki daftarnya sendiri di [Verify destinations](/docs/guides/verify/destinations), dan di sana semua negara aktif sejak awal. Karena itu, kredensial dengan akses tulis `verify` dapat mengirim kode melalui SMS ke negara yang diblokir allowlist ini. Jika agen memegang `verify`, nonaktifkan juga di halaman tersebut negara yang tidak Anda layani.

Aktifkan negara di [**SMS** > **Destinations**](https://bird.com/dashboard/w/sms/destinations), dengan `bird sms destinations update`, atau dengan tool MCP `sms_destinations_update`:

```bash
bird sms destinations update --destination NL=true
```

Mengubah allowlist memerlukan scope `sms_management` pada level `write`. Kredensial yang hanya memegang `sms` dapat mengirim ke negara yang sudah aktif, tetapi tidak dapat mengaktifkan negara lain. Berikan `sms` kepada agen pengirim, dan simpan `sms_management` untuk kredensial yang mengonfigurasi workspace.

[Mengirim SMS](/docs/guides/sms/sending-sms#before-you-send-enable-the-destination-country) menjelaskan kondisi awal allowlist dan cara negara asal ditambahkan.

## Batasi pengeluaran harian SMS untuk setiap negara

Setiap negara tujuan dapat memiliki batas pengeluaran harian dalam mata uang wallet Anda. Setelah pengeluaran hari itu ke negara tersebut mencapai batas, pesan baru ke sana ditolak dengan `422 SMSDestinationDailySpendExceeded` hingga tengah malam UTC. Batas nol memblokir negara tersebut.

Kode verifikasi yang dikirim melalui SMS ikut dihitung dalam batas. Saat batas tercapai, Verify berhenti mengirim kode melalui SMS ke negara tersebut dan mencoba channel berikutnya yang aktif untuk negara itu. Jika tidak ada channel tersisa, verifikasi gagal dengan `422 NoAvailableChannel`.

Atur batas di tiga tempat yang sama dengan allowlist. Perintah ini mengaktifkan Belanda dan membatasinya hingga 25 EUR per hari, di workspace yang wallet-nya menggunakan EUR:

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

Batas ini tidak presisi. Perubahan batas memerlukan waktu hingga satu menit sebelum berlaku pada pengiriman. Pengeluaran dihitung saat pesan ditagih, sehingga pesan yang sudah diterima dapat membuat total hari itu melampaui batas sebesar biaya pesan tersebut. Tetapkan batas dengan memperhitungkan selisih itu. `bird sms destinations list` menampilkan batas setiap negara dan penggunaan hari itu terhadap batas tersebut.

Menetapkan batas memerlukan akses tulis `sms_management` yang sama dengan daftar izin, sehingga kredensial yang hanya memiliki `sms` tidak dapat menaikkan batasnya sendiri. [Mengirim SMS](/docs/guides/sms/sending-sms#before-you-send-enable-the-destination-country) memuat aturan lengkapnya.

## Batasi total pengeluaran dengan dompet prabayar

Pengiriman bayar sesuai pemakaian diambil dari dompet prabayar organisasi Anda. Apa yang terjadi saat saldo tidak cukup untuk suatu pengiriman bergantung pada kanalnya:

- **SMS dan WhatsApp** ditolak di API dengan `402`. Pesan yang sudah diterima saat penagihannya gagal berakhir `rejected` dan tidak ditagih.
- **Email pada paket Email berbayar** ditagih tidak lama setelah dikirim, sehingga saldo dapat sesaat berada di bawah nol. Setelah dompet tidak memiliki saldo atau kredit lagi, email baru ditolak dengan `402` hingga dana ditambahkan.
- **Biaya saat pengiriman** yang tidak dapat ditutupi saldo akan dilewati, dan pesan tetap sampai ke penerimanya.

Dompet yang kosong menghentikan pengeluaran berikutnya, tetapi tidak membatasi pengeluaran tepat pada jumlah saldo. Isi dompet dengan cadangan untuk pengiriman yang ditagih setelah diterima. Jika isi ulang otomatis aktif, dompet terisi kembali dari kartu tersimpan saat saldo turun di bawah ambang batas Anda, sehingga saldo saja tidak lagi membatasi pengeluaran agen. [Billing & usage](/docs/guides/billing-and-usage#the-wallet) adalah sumber aturan ini.

Operasi penagihan memerlukan izin penagihan organisasi, `org:billing`. Kunci API tidak dapat memiliki izin ini, sehingga tidak ada kunci yang dapat mengisi ulang dompet, mengubah paket, atau membaca penggunaan. Token OAuth dapat memilikinya jika orang yang menyetujui proses masuk memiliki izin tersebut dan memberikan izin organisasi, seperti yang dapat dilakukan pemilik organisasi. Kredensial dari pendaftaran mandiri memilikinya sejak awal. Berikan kunci dengan cakupan terbatas kepada agen yang berjalan tanpa pengawasan, sehingga penambahan dana tetap berada di tangan pemilik anggaran.

[Metode pembayaran dan dompet](/docs/knowledge-base/billing/payment-methods-wallet) membahas isi ulang, isi ulang otomatis, dan peringatan saldo rendah.

## Langkah berikutnya

- [Pendaftaran mandiri](/docs/ai/self-serve-signup): buat akun tempat agen bekerja, dari terminal.
- [Autentikasi & kunci API](/docs/guides/authentication): scope, kedaluwarsa, rotasi, dan pencabutan.
- [Batas laju](/docs/guides/rate-limits): batas permintaan yang berlaku untuk semua kunci di organisasi Anda.
- [Berikan agen nomor telepon dan kotak masuknya sendiri](/docs/ai/agent-number-and-inbox): identitas yang digunakan agen untuk mengirim dan menerima pesan.

## Related resources

- [Setting up your coding agent](/learn/basics/setting-up-your-coding-agent) (video)
- [What is an MCP server, and how does an agent use one to send messages?](/explained/platform/what-is-an-mcp-server-and-how-does-an-agent-send-messages) (answer)
- [Coding agents](/ai) (product)
- [Build with AI agents](/learn/paths/agents) (course)

[Get an implementation brief](/learn/workspace?topic=agents)
