Cara Mencegah Agen AI Melumpuhkan API yang Berfungsi

Memberikan agen AI akses tulis ke proyek API dapat menyebabkan kerusakan nyata—bukan karena agen berniat buruk, tetapi karena agen menjalankan instruksi secara literal. Perintah seperti “bersihkan endpoint pengguna” dapat menghapus rute aktif, sedangkan “perbarui skema” dapat menimpa model data yang dipakai endpoint lain. Agen tidak mengetahui apa yang sedang berjalan di produksi; ia hanya melihat sumber daya yang diizinkan untuk diubah.

Coba Apidog hari ini

Ini adalah kelas risiko baru. Saat manusia menghapus endpoint, biasanya ada jeda untuk memeriksa dampaknya. Agen yang berjalan dalam loop terminal akan menjalankan perintah, menerima respons sukses, lalu lanjut ke langkah berikutnya. Jika targetnya adalah main, perubahan itu sudah masuk ke sumber desain API Anda.

Solusinya bukan membatasi agen hingga tidak berguna. Solusinya adalah memberi agen sandbox yang tidak dapat ia tinggalkan. AI Branch di Apidog mengisolasi setiap pengeditan agen ke cabang terpisah. Cabang sumber tetap aman, dan tidak ada perubahan yang masuk ke main sampai manusia meninjau diff lalu menggabungkannya.

Untuk latar belakang desain fitur ini, baca AI Branch dan perubahan yang lebih aman yang digerakkan agen. Artikel ini berfokus pada implementasi alur CLI yang aman.

Mengapa akses tulis agen berbahaya secara default

Sebagian besar alat memberi agen satu tingkat akses: proyek. Jika agen dapat membuat endpoint, ia juga dapat menghapusnya. Jika ia dapat memperbarui skema, ia juga dapat menggantinya dengan versi yang tidak kompatibel.

Tanpa isolasi, tidak ada jeda antara dua hal berikut:

1. Agen mengusulkan perubahan.
2. Perubahan masuk ke sumber kebenaran API Anda.

Tiga mode kegagalan yang umum adalah:

• Menimpa (overwrite). Agen membuat ulang skema berdasarkan pemahaman parsial, lalu menghapus kolom yang dibutuhkan endpoint lain.
• Menghapus (delete). Agen “mengonsolidasikan” endpoint dan menghapus rute yang masih digunakan klien aktif.
• Penyimpangan diam-diam (silent drift). Agen membuat banyak perubahan kecil sepanjang sesi. Setiap perubahan tampak wajar, tetapi hasil akhirnya menyimpang dari API yang seharusnya dikirim.

Ini bukan perilaku aneh. Ini adalah hasil normal ketika agen bekerja pada cabang yang salah. Tujuannya adalah membuat cabang produksi tidak dapat dijangkau langsung oleh agen.

Perbaikan inti: cabang AI yang terisolasi

AI Branch adalah jenis cabang sprint untuk operasi AI eksternal dan CLI. Agen dapat membuat perubahan di dalam cabang ini tanpa memengaruhi cabang sumber atau main.

Mulai dengan menginstal dan mengautentikasi Apidog CLI:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>

Buat cabang AI dari main. Gunakan nama yang mencantumkan tanggal, cabang sumber, dan tujuan pekerjaan agar mudah dilacak:

apidog branch create --type ai \
  --name "ai/20260708-from-main-user-register" \
  --from main \
  --project <PROJECT_ID>

Perhatikan dua hal penting:

• Cabang dibuat dari main, tetapi proses ini tidak mengubah main.
• AI Branch dimulai dalam keadaan kosong. Cabang ini tidak otomatis menyalin seluruh proyek Anda.

Sifat kosong ini adalah kontrol keamanan. Agen hanya dapat mengubah sumber daya yang Anda masukkan secara eksplisit ke cabang tersebut. Radius dampak dibatasi oleh scope tugas, bukan oleh seluruh proyek API.

Untuk melihat opsi lengkap perintah cabang:

apidog branch create -h

Impor sumber daya sebelum mengeditnya

Karena AI Branch kosong, Anda harus memasukkan endpoint, skema, atau dokumen yang memang dibutuhkan agen. Jangan impor seluruh proyek jika tugasnya hanya mengubah satu alur API.

Contoh: impor endpoint 1 dan 2, serta skema data 3 dari main ke AI Branch.

apidog branch pick-to \
  --type ai \
  --from main \
  --to "ai/20260708-from-main-user-register" \
  --endpoint-ids 1,2 \
  --data-schema-ids 3 \
  --project <PROJECT_ID>

Setelah perintah ini:

• Cabang AI berisi salinan endpoint 1 dan 2.
• Cabang AI berisi salinan skema 3.
• Versi asli di main tidak berubah.

Jika agen menghapus endpoint dalam cabang AI, yang terhapus hanya salinannya. Endpoint aktif di main tetap aman.

Saat menggunakan agen pengodean, perintah ini dapat dijalankan langsung dari loop agen. Apidog CLI mengembalikan JSON terstruktur, termasuk agentHints.nextSteps, sehingga agen dapat membaca hasil perintah dan menentukan langkah selanjutnya. Lihat juga contoh integrasi apidog-cli di Cursor.

Biarkan agen mengedit, lalu tinjau diff

Setelah sumber daya tersedia di AI Branch, agen dapat membuat, memperbarui, atau menghapus:

• endpoint;
• skema data;
• dokumentasi;
• skenario pengujian.

Semua operasi tulis tetap berada di cabang AI.

Setelah agen selesai, tinjau perubahan sebelum melakukan penggabungan. Periksa diff dari CLI atau klien Apidog, lalu verifikasi bahwa perubahan tersebut sesuai dengan tugas yang diberikan.

Gunakan checklist sederhana saat meninjau:

• Apakah endpoint yang berubah memang berada dalam scope tugas?
• Apakah field skema yang dihapus masih dipakai endpoint lain?
• Apakah status code, request body, dan response body tetap kompatibel?
• Apakah agen menambahkan perubahan yang tidak diminta?
• Apakah sumber daya yang akan digabungkan sudah dibatasi dengan ID yang tepat?

Tinjauan ini wajib. Jika agen menyimpang, buang cabangnya. Jangan memperbaiki dampaknya setelah perubahan masuk ke produksi.

Selesaikan perubahan dengan permintaan gabungan

Strategi penggabungan bergantung pada apakah cabang target dilindungi.

Jika target tidak dilindungi, Anda dapat menggabungkan sumber daya tertentu secara langsung:

apidog branch merge \
  --type ai \
  --from "ai/20260708-from-main-user-register" \
  --to main \
  --endpoint-ids 1,2 \
  --data-schema-ids 3 \
  --project <PROJECT_ID>

Namun, untuk main, sebaiknya aktifkan perlindungan cabang. Jika main dilindungi, penggabungan langsung diblokir. Buat permintaan gabungan agar perubahan melewati proses review:

apidog merge-request create \
  --from "ai/20260708-from-main-user-register" \
  --to main \
  --endpoint-ids 1,2 \
  --data-schema-ids 3 \
  --reviewer-ids <REVIEWER_USER_IDS> \
  --description "AI branch: user register changes" \
  --project <PROJECT_ID>

Permintaan gabungan adalah jalur yang direkomendasikan untuk perubahan dari agen karena:

• perubahan harus ditinjau oleh manusia;
• agen tidak dapat menulis langsung ke main;
• hanya resource ID yang dicantumkan yang ikut digabungkan;
• perubahan di luar scope dapat dibiarkan tetap berada di cabang AI.

Alur ini sama seperti kolaborasi manusia dalam API Git-native: buat cabang, usulkan perubahan, tinjau, lalu gabungkan.

Bersihkan cabang yang digabungkan atau ditinggalkan

Gunakan satu AI Branch untuk satu tugas agen. Setelah cabang digabungkan atau tidak lagi dibutuhkan, arsipkan agar daftar cabang tetap mudah dibaca.

apidog branch archive "ai/20260708-from-main-user-register" \
  --type ai \
  --project <PROJECT_ID>

Ritme kerja yang disarankan:

1. Buat satu cabang AI untuk satu tugas.
2. Impor resource minimum yang diperlukan.
3. Biarkan agen bekerja.
4. Tinjau hasilnya.
5. Gabungkan atau tolak perubahan.
6. Arsipkan cabang.

Jangan gunakan satu cabang AI untuk mengumpulkan banyak sesi agen yang tidak terkait. Semakin banyak pekerjaan tercampur dalam satu cabang, semakin sulit review dilakukan dengan benar.

Kebersihan agen yang aman di sekitar cabang

AI Branch menyediakan isolasi, tetapi tetap perlu dilengkapi dengan kontrol operasional.

1. Gunakan token dengan hak istimewa paling rendah

Token yang digunakan pada perintah berikut menentukan apa yang dapat dilakukan agen:

apidog login --with-token <YOUR_ACCESS_TOKEN>

Berikan token otomatisasi akses hanya ke proyek yang diperlukan. Jangan gunakan token pemilik pribadi hanya karena lebih praktis.

Jika token bocor atau agen melakukan operasi yang tidak diharapkan, dampaknya tetap dibatasi oleh scope token.

2. Lindungi main

Perlindungan cabang mengubah “review sebelum merge” dari sekadar kebiasaan menjadi aturan teknis.

Dengan main yang dilindungi:

• merge langsung diblokir;
• perubahan harus melalui merge-request create;
• reviewer manusia menjadi bagian wajib dari jalur rilis.

3. Tinjau sebelum merge, setiap kali

Isolasi hanya berguna jika seseorang benar-benar membaca diff. Agen yang akurat selama seminggu tetap dapat salah memahami instruksi pada sesi berikutnya.

Jadikan review sebagai tahap eksplisit dalam workflow CI/CD atau checklist tim Anda.

4. Delegasikan, lalu verifikasi

Pola kerja yang aman adalah:

1. Delegasikan tugas yang spesifik kepada agen.
2. Batasi resource yang dapat disentuh agen.
3. Jalankan agen di cabang terisolasi.
4. Verifikasi output sebelum merge.

Pola yang sama berlaku saat agen menjalankan pengujian. Agen dapat menjalankan suite, tetapi Anda tetap memeriksa hasil test harness dan kode keluarnya sebelum mempercayai hasil tersebut.

Jika spesifikasi API juga diberi versi di Git, gunakan kontrol versi OpenAPI sebagai lapisan riwayat tambahan saat ada perubahan yang terlihat mencurigakan.

Alur ujung-ke-ujung

Berikut urutan yang dapat Anda jalankan sendiri atau berikan kepada agen:

1. Buat AI Branch dari main.

   apidog branch create --type ai \
     --name "ai/20260708-from-main-user-register" \
     --from main \
     --project <PROJECT_ID>

1. Impor endpoint dan skema yang diperlukan saja.

   apidog branch pick-to \
     --type ai \
     --from main \
     --to "ai/20260708-from-main-user-register" \
     --endpoint-ids 1,2 \
     --data-schema-ids 3 \
     --project <PROJECT_ID>

1. Biarkan agen mengedit resource dalam cabang AI.

2. Tinjau diff dan validasi perubahan.

3. Buat merge request ke main yang dilindungi.
   

   apidog merge-request create \
     --from "ai/20260708-from-main-user-register" \
     --to main \
     --endpoint-ids 1,2 \
     --data-schema-ids 3 \
     --reviewer-ids <REVIEWER_USER_IDS> \
     --description "AI branch: user register changes" \
     --project <PROJECT_ID>

1. Setelah merge atau penolakan, arsipkan cabang.

   apidog branch archive "ai/20260708-from-main-user-register" \
     --type ai \
     --project <PROJECT_ID>

Dengan alur ini, agen tidak memiliki jalur langsung untuk menimpa atau menghapus endpoint aktif di main. Dampak terburuknya adalah membuat perubahan buruk pada salinan yang kemudian Anda tolak.

Berikan ruang bagi agen untuk bekerja tanpa memberi mereka kunci produksi

Agen berguna karena dapat bertindak cepat tanpa meminta konfirmasi untuk setiap langkah. Karakteristik yang sama membuat akses tulis tanpa batas menjadi berbahaya.

Gunakan kombinasi berikut:

• AI Branch yang terisolasi;
• main yang dilindungi;
• token dengan hak istimewa paling rendah;
• review manusia sebelum merge.

Dengan kontrol tersebut, risiko “agen menghancurkan API kami” berubah menjadi diff yang dapat Anda periksa dan tolak sebelum menyentuh sumber API utama.

Apidog menyediakan alur ini tanpa perlu merangkai banyak alat terpisah. Mulai dengan Apidog CLI, buat AI Branch, dan arahkan agen untuk mengedit salinan alih-alih objek asli. Unduh Apidog untuk mencoba alur AI Branch, lalu baca dokumentasi AI Branch sebelum menghubungkannya ke workflow produksi.