Prompt dan cakupan
Ubahlah API manajemen proyek yang dirancang untuk pengembang manusia menjadi API yang dapat dipanggil oleh agen AI secara andal. Jelaskan deskripsi operasi, input, output, paginasi, error, konfirmasi penulisan, batas laju, dan keamanan. Prompt ini merujuk pada Internet-Draft IETF Juni 2026 "Agent-Friendly HTTP API Profile". Dokumen ini bersifat Informasi (Informational) dan masih dalam tahap pengembangan; dokumen ini tidak mendefinisikan protokol, identitas, atau mekanisme otorisasi baru.
Hal yang diuji oleh pewawancara
- Memperlakukan deskripsi yang dapat dibaca mesin sebagai kontrak, bukan dokumentasi yang dibuat setelahnya.
- Mengurangi pilihan yang salah dengan nama yang stabil, skema yang ketat, respons yang dibatasi, dan paginasi kursor.
- Menjadikan error, percobaan ulang (retry), idempotensi, pratinjau, dan pembatalan (undo) sebagai sinyal yang dapat ditindaklanjuti.
- Memisahkan kegunaan API dari identitas agen, otorisasi, dan keamanan injeksi prompt.
Pertanyaan untuk diklarifikasi sebelum menjawab
- Apakah agen akan menemukan API melalui OpenAPI, lapisan alat MCP, atau katalog khusus?
- Operasi mana yang hanya-baca (read-only) dan mana yang memberi notifikasi, menagih biaya, atau mengubah status?
- Apakah respons memerlukan pemilihan bidang (field selection), paginasi kursor, dan ukuran halaman maksimum?
- Bisakah klien memberikan kunci idempotensi dan mengambil hasil asli setelah batas waktu habis (timeout)?
- Bidang mana yang dikembalikan yang berisi konten pengguna tidak tepercaya yang harus diisolasi dari bidang kontrol?
Kerangka jawaban 30 detik
Perlakukan deskripsi API dan perilaku HTTP sebagai satu kontrak input. Jaga agar nama operasi tetap stabil dan menyatakan niat dengan jelas, tolak properti input yang tidak dikenal, kembalikan respons kecil dengan pemilihan bidang, dan lakukan paginasi koleksi dengan kursor. Error harus memuat kode yang stabil, kemampuan untuk dicoba ulang, dan tindakan selanjutnya; operasi penulisan mendukung kunci idempotensi, pratinjau, konfirmasi, dan pembatalan. Server menerapkan batas, otorisasi, dan audit; server tidak dapat mendelegasikan keputusan keamanan kepada agen. Dokumen IETF adalah daftar periksa draf, bukan protokol autentikasi.
Pembahasan mendalam langkah demi langkah
1. Pisahkan lapisan API dan alat
OpenAPI dan deskripsi serupa yang dapat dibaca mesin termasuk dalam lapisan API; MCP dan protokol pemanggilan alat lainnya termasuk dalam lapisan alat. Bangun kontrak API yang stabil dan dapat diverifikasi terlebih dahulu sehingga beberapa lapisan alat dapat menggunakannya kembali. Jangan jadikan prompt atau nama alat satu agen sebagai satu-satunya batas keamanan.
2. Rancang operasi yang mudah dibedakan
ID Operasi harus stabil, singkat, dan mencerminkan niat. Pada cakupan alat yang luas, nama yang mengutamakan entitas seperti task_create dan task_update dapat lebih mudah dibedakan daripada prefiks bersama create_. Deskripsi harus menyatakan kapan harus dan kapan tidak boleh menggunakan suatu operasi, efek sampingnya, dan operasi pencarian mana yang digunakan untuk mendapatkan pengidentifikasi yang hilang.
3. Batasi input dan output
Skema input harus menentukan bidang wajib, enum tertutup, panjang, dan batas array, serta menolak properti yang tidak dikenal. Respons harus berukuran kecil secara default dan mendukung pemilihan bidang atau tingkat kerincian (verbosity). Jangan mengandalkan klien untuk meminta lebih sedikit data; server tetap mengontrol biaya dan penggunaan konteks.
{
"name": "task_create",
"description": "Create a task; notifies the assignee.",
"inputSchema": {
"type": "object",
"additionalProperties": false,
"required": ["project_id", "title", "idempotency_key"],
"properties": {
"project_id": {"type": "string"},
"title": {"type": "string", "maxLength": 200},
"priority": {"type": "string", "enum": ["low", "medium", "high"]},
"idempotency_key": {"type": "string", "maxLength": 128}
}
}
}4. Buat operasi baca dan paginasi dapat dipulihkan
Kembalikan kursor buram (opaque cursor) alih-alih meminta agen menghitung offset. Ikatkan kursor ke kueri, berikan masa kedaluwarsa, dan kembalikan next_cursor beserta tindakan selanjutnya yang siap digunakan. Pengurutan yang stabil, permintaan bersyarat, dan pemilihan bidang mengurangi transfer duplikat dan penggunaan konteks.
5. Buat error dapat ditindaklanjuti oleh mesin
Kembalikan kode yang stabil, detail terstruktur, dan tanda retryable; sertakan tautan operasi berikutnya jika berguna. Respons 429 harus memberikan penundaan percobaan ulang, error validasi harus mengidentifikasi bidang yang bermasalah, dan tugas yang berjalan lama harus memberikan URL status. Bahasa alami membantu manusia, tetapi tidak dapat menjadi satu-satunya semantik kontrol.
{
"type": "https://api.example/problems/rate-limit",
"title": "Too many requests",
"status": 429,
"code": "RATE_LIMITED",
"retryable": true,
"retry_after_seconds": 30
}6. Lindungi operasi penulisan
Operasi penulisan menerima kunci idempotensi dengan jendela waktu dan cakupan yang terdokumentasi. Percobaan ulang setelah batas waktu habis akan mengembalikan hasil asli alih-alih membuat duplikat. Penulisan berisiko tinggi menyediakan uji coba (dry-run), konfirmasi, atau pembatalan, serta menyatakan efek samping seperti notifikasi, penagihan biaya, dan lainnya. Server tetap melakukan pemeriksaan otorisasi, kuota, dan audit.
7. Tetapkan batas keamanan dan observabilitas
Tandai teks pengguna atau pihak ketiga sebagai data dan pisahkan dari bidang kontrol tepercaya untuk mengurangi injeksi prompt tidak langsung. Batasi ukuran respons, ukuran halaman, polling, dan namespace alat; terapkan hak istimewa paling rendah (least privilege) dan konfirmasi manusia untuk operasi berisiko tinggi. Catat ID korelasi, pelaku (actor), delegasi, hasil, dan percobaan ulang tanpa mencatat konten sensitif.
8. Validasi dan lakukan iterasi
Gunakan serangkaian tugas tetap untuk mengukur akurasi pemilihan operasi, kesalahan parameter, penulisan duplikat, error yang dapat dipulihkan, ukuran respons rata-rata, penggunaan konteks, keberhasilan setelah 429, dan cakupan konfirmasi. Buat versi untuk deskripsi, skema, error, dan respons. Ubah rekomendasi draf menjadi daftar periksa internal alih-alih menjanjikan kompatibilitas standar.
Contoh jawaban berkualitas tinggi
Saya akan memperlakukan deskripsi API sebagai kontrak utama dan merancang perilaku HTTP di sekitarnya. ID Operasi bersifat stabil serta mengekspresikan entitas dan niat; deskripsi menyatakan kondisi penggunaan, kasus terlarang, dan efek samping. Skema input menolak bidang yang tidak dikenal serta membatasi enum, panjang, array, dan halaman. Koleksi menggunakan kursor buram dan pengurutan stabil, sementara respons berukuran kecil dan bidangnya dapat dipilih.
Error memuat kode yang stabil, kemampuan percobaan ulang, retry_after, dan tindakan berikutnya. Operasi penulisan memerlukan kunci idempotensi dan mengembalikan hasil asli setelah batas waktu habis; penulisan berisiko tinggi mendukung pratinjau, konfirmasi, atau pembatalan. Server menerapkan otorisasi, batas laju, ukuran, dan audit, alih-alih memercayai agen untuk mengikuti instruksi teks bebas. Konten pengguna diisolasi dari bidang kontrol, dan penyedia alat menggunakan namespace terpisah dengan ID korelasi.
Terakhir, evaluasi serangkaian tugas untuk pilihan yang salah, kesalahan parameter, penulisan duplikat, ukuran respons, keberhasilan percobaan ulang, dan cakupan konfirmasi. Dokumen IETF adalah draf Informasi (Informational) Juni 2026 tanpa protokol autentikasi atau otorisasi, jadi saya akan menggunakannya sebagai daftar periksa desain dengan pembuatan versi internal dan kemampuan rollback.
Kesalahan umum
- Menyebut profil tersebut sebagai protokol identitas atau otorisasi baru.
- Mengoptimalkan prompt tetapi membiarkan OpenAPI, skema, error, dan efek samping kurang terspesifikasi.
- Meminta agen untuk membatasi ukuran respons atau menghitung offset paginasi.
- Mengabaikan idempotensi, pratinjau, konfirmasi, atau pembatalan dari operasi penulisan yang dapat dicoba ulang.
- Memasukkan teks pengguna yang dikembalikan ke dalam bidang instruksi tepercaya dan mengabaikan injeksi prompt tidak langsung.
Pertanyaan lanjutan dan tanggapan
Mengapa tidak menulis dokumentasi yang lebih mendalam saja?
Agen memilih dari deskripsi dan respons yang dapat dibaca mesin pada setiap langkah. Bidang yang stabil, enum, tanda error, dan kursor lebih mudah dieksekusi daripada saran yang tersebar di seluruh teks penjelasan; dokumentasi tetap berguna bagi manusia dan proses migrasi.
Lapisan mana yang bertanggung jawab atas keamanan, API atau MCP?
API harus menerapkan autentikasi, otorisasi, batas laju, dan audit. Lapisan alat dapat membatasi eksposur, namespace, dan konfirmasi, tetapi tidak dapat menggantikan kontrol akses di sisi server.
Bagaimana Anda memutuskan operasi penulisan mana yang memerlukan konfirmasi?
Klasifikasikan berdasarkan ketidakterbalikkan (irreversibility), jumlah, pengungkapan data, notifikasi eksternal, dan cakupan hak istimewa. Operasi berisiko tinggi mengekspos uji coba atau token konfirmasi; pembaruan idempoten berisiko rendah dapat berjalan secara otomatis, tetapi server selalu memvalidasinya.
Bagaimana jika deskripsi tercemar oleh konten pihak ketiga?
Tempatkan teks pihak ketiga dalam bidang data eksplisit dan cegah agar tidak mengubah definisi alat atau izin. Isolasi namespace penyedia, sematkan sidik jari (fingerprint), audit versi, dan periksa kembali otorisasi di server.