DEV Community

Cover image for Desain Skema Alat: Bantu Agen AI Memilih Endpoint yang Tepat
Walse
Walse

Posted on Originally published at apidog.com

Desain Skema Alat: Bantu Agen AI Memilih Endpoint yang Tepat

Cara Membuat Model Memilih Tool yang Tepat

Anda memberi agen dua tool: updateUser dan deactivateUser. Sebuah tiket dukungan mengatakan, “tutup akun ini.” Agen memanggil deactivateUser. Minggu lalu, tiket yang hampir sama membuatnya memanggil updateUser dengan status: "closed", yang diterima API Anda dan memiliki arti berbeda di hilir.

Coba Apidog hari ini

Tidak ada yang rusak. Model hanya memilih antara dua opsi masuk akal berdasarkan deskripsi yang tidak membedakan keduanya. Pemilihan tool sering disalahkan pada model, padahal perbaikan pertama biasanya ada di skema—satu-satunya sumber konteks yang dibaca model saat memilih tool.

Panduan ini membahas cara menulis nama, deskripsi, dan parameter tool agar lebih jelas; cara menyatakan prasyarat; serta cara menguji pemilihan tool supaya perubahan kecil pada teks tidak menyebabkan regresi.

Jika tool Anda dibuat dari spesifikasi API, seperti pada panduan mengubah spesifikasi OpenAPI menjadi tool agen, deskripsi tersebut sebaiknya diperbaiki langsung di spesifikasi. Apidog memungkinkan definisi API, dokumentasi, mock, dan tool agen tetap sinkron.

Ilustrasi pemilihan tool agen

Apa yang dilihat model?

Saat memilih tool, model memiliki:

  • Percakapan pengguna
  • System prompt
  • Daftar definisi tool
  • Nama, deskripsi, dan skema parameter setiap tool

Model tidak melihat dokumentasi API, komentar kode, atau pengetahuan internal bahwa updateUser adalah endpoint lama.

Karena itu, semua konteks yang diperlukan untuk membedakan tool harus ditulis di definisinya. Baik panduan pemanggilan fungsi OpenAI maupun dokumentasi penggunaan tool Anthropic menekankan pentingnya deskripsi yang jelas dan spesifik.

Kesalahan pemilihan biasanya muncul dalam empat bentuk:

Masalah Perbaikan
Model memilih tool yang mirip Jelaskan kapan tool digunakan dan kapan tidak digunakan
Model tidak memilih tool apa pun Gunakan kosakata yang dipakai pengguna
Tool benar, argumen salah Gunakan tipe, enum, unit, dan contoh
Urutan pemanggilan salah Nyatakan prasyarat di deskripsi

1. Namai tool sesuai fungsinya

Nama membawa sinyal penting karena biasanya dibaca model sebelum detail lainnya.

Gunakan konvensi yang konsisten

Gunakan format kataKerjaKataBenda di seluruh kumpulan tool:

createOrder
refundOrder
getOrderStatus
Enter fullscreen mode Exit fullscreen mode

Jangan mencampur format seperti:

order_create
getOrder
refund
Enter fullscreen mode Exit fullscreen mode

Konsistensi membuat setiap nama lebih mudah dipindai dan dibandingkan.

Sebutkan objek dan cara kerjanya

search terlalu umum.

Gunakan nama yang lebih spesifik:

searchCustomersByEmail
Enter fullscreen mode Exit fullscreen mode

Nama tersebut langsung menjelaskan objek yang dicari dan metode pencariannya.

Hindari jargon internal

Jika API menyebut pelanggan sebagai “entitas” dan langganan sebagai “instrumen”, model mungkin tidak menghubungkannya dengan tiket yang menggunakan kata “pelanggan” dan “paket”.

Namai tool berdasarkan bahasa tugas, bukan bahasa internal skema.

Jangan gunakan nama yang sama di seluruh konteks. Dua tool bernama list, meskipun berada di namespace berbeda, tetap membingungkan ketika keduanya muncul dalam satu daftar.

2. Tulis deskripsi yang membedakan

Deskripsi yang berguna menjawab empat pertanyaan:

  1. Apa yang dilakukan tool?
  2. Apa yang diubah?
  3. Kapan tool digunakan?
  4. Kapan tool tidak boleh digunakan?

Deskripsi yang lemah 

{ "name": "updateUser", "description": "Updates a user." }
{ "name": "deactivateUser", "description": "Deactivates a user." }
Enter fullscreen mode Exit fullscreen mode

Deskripsi yang membedakan 

{
  "name": "updateUser",
  "description": "Updates profile fields on an active user, such as name, email, or timezone. Use for corrections and profile edits requested by the user. Does NOT change account status. To disable an account, use deactivateUser instead. Do not use to close or cancel an account."
}
{
  "name": "deactivateUser",
  "description": "Disables a user account, revoking all sessions and blocking sign-in. Reversible with reactivateUser. Use when a customer asks to close, cancel, pause, or suspend their account. Does NOT delete data. For permanent deletion use deleteUser, which cannot be undone."
}
Enter fullscreen mode Exit fullscreen mode

Empat teknik penting digunakan di sana:

  • Sebutkan tool saudaranya. Kalimat “gunakan deactivateUser sebagai gantinya” mengatasi ambiguitas saat model membandingkan kedua tool.
  • Gunakan kosakata pengguna. Kata “tutup”, “batalkan”, “jeda”, dan “tangguhkan” lebih cocok dengan tiket dukungan daripada istilah internal.
  • Jelaskan batasan negatif. “Tidak mengubah status akun” lebih membedakan daripada sekadar “memperbarui profil”.
  • Tandai reversibilitas. Model dapat mempertimbangkan risiko jika Anda menjelaskan apakah tindakan bisa dibatalkan.

Deskripsi 100 kata tetap murah jika mencegah satu panggilan keliru ke endpoint destruktif.

Pola ini juga sejalan dengan pelindung agen AI: jelaskan risikonya di definisi tool, tetapi tetap enforce aturan di executor.

3. Rancang parameter agar argumen salah sulit dibuat

Setelah tool yang tepat dipilih, parameter menjadi sumber kesalahan berikutnya.

JSON Schema Validation menyediakan sebagian besar batasan yang dibutuhkan.

Gunakan enum untuk nilai yang terbatas

Parameter bertipe string membuat model menebak nilai. Gunakan enum:

"status": {
  "type": "string",
  "enum": ["pending", "paid", "refunded", "cancelled"],
  "description": "Order status. 'cancelled' means never fulfilled; 'refunded' means fulfilled then reversed."
}
Enter fullscreen mode Exit fullscreen mode

Sertakan unit dalam nama

amount ambigu: apakah nilainya dolar atau sen?

Gunakan nama eksplisit:

amount_cents
timeout_seconds
distance_meters
duration_ms
Enter fullscreen mode Exit fullscreen mode

Berikan contoh format 

"description": "Start date in ISO 8601 format, for example 2026-08-26"
Enter fullscreen mode Exit fullscreen mode

Contoh seperti ini jauh lebih efektif daripada hanya menulis "start date".

Pastikan parameter wajib sesuai kenyataan

Semua parameter opsional dapat memindahkan kesalahan ke runtime. Sebaliknya, menandai parameter sebagai wajib ketika API sebenarnya memiliki default juga dapat membuat model menciptakan nilai.

Pastikan definisi tool mencerminkan validasi API yang sebenarnya. Lihat juga panduan desain pesan error API untuk agen.

Pilih struktur flat jika memungkinkan

Model lebih mudah mengisi:

{
  "customer_postal_code": "10110"
}
Enter fullscreen mode Exit fullscreen mode

daripada struktur bertingkat:

{
  "customer": {
    "address": {
      "postal_code": "10110"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Ratakan struktur di batas tool, lalu rakit kembali di executor.

Pisahkan tool yang terlalu fleksibel

Tool dengan parameter mode yang mengubah arti semua field lain biasanya sebenarnya terdiri dari dua tool. Memisahkannya akan meningkatkan akurasi pemilihan sekaligus menyederhanakan skema.

4. Nyatakan prasyarat dan urutan

Alur multi-langkah gagal ketika model tidak mengetahui urutannya. Nyatakan ketergantungan langsung di deskripsi:

{
  "name": "captureCharge",
  "description": "Captures a previously authorized charge. Requires an authorization_id from authorizeCharge. Call authorizeCharge first if you do not already have one. Cannot capture more than the authorized amount."
}
Enter fullscreen mode Exit fullscreen mode

Dua baris tersebut sudah menjelaskan:

  • Tool yang harus dipanggil lebih dulu
  • Data yang harus dihasilkan tool sebelumnya
  • Batasan jumlah yang boleh ditangkap

Pola yang sama berlaku untuk:

  • Membuat sebelum memperbarui
  • Mengunggah sebelum memproses
  • Mengotorisasi sebelum menangkap pembayaran

Jika deskripsi tool bergantung tidak menyebutkan langkah sebelumnya, model bisa melewatinya. Untuk alur yang melibatkan beberapa agen, gunakan prinsip meneruskan konteks antar sub-agen.

5. Uji pemilihan tool seperti perilaku lain

Deskripsi adalah bagian dari kode dan dapat mengalami regresi. Satu perubahan gaya bahasa dapat membuat agen memilih endpoint yang salah.

Bangun suite pemilihan kecil

Mulai dengan 20–50 prompt. Setiap prompt harus memiliki tool yang diharapkan.

Catat hanya:

  • Tool yang dipilih
  • Apakah model seharusnya memanggil tool atau meminta klarifikasi

Argumen dapat sedikit berbeda antar-eksekusi, tetapi pilihan tool harus stabil. Ini merupakan bentuk praktis dari pengujian agen non-deterministik.

Prioritaskan kasus yang mudah rusak

Masukkan:

  • Dua tool paling mirip, dengan prompt untuk masing-masing
  • Prompt menggunakan bahasa pelanggan, bukan istilah API
  • Prompt yang tidak cocok dengan tool apa pun
  • Tool destruktif, ketika kesalahan memiliki dampak nyata

Jalankan setiap prompt beberapa kali. Tool yang menang 4 dari 5 percobaan masih terlalu tidak stabil untuk produksi.

Gunakan mock, bukan data produksi

Arahkan eksekusi ke mock agar pengujian tidak menyentuh data langsung. Ikuti panduan menjalankan agen terhadap mock, bukan produksi.

Apidog dapat membuat mock dari definisi API yang sama dengan sumber tool agen. Dengan begitu, skema dan perilaku tetap selaras.

Contoh mock API untuk pengujian agen

Tiga kumpulan tool yang sering bermasalah

1. Kumpulan CRUD

API lama mungkin mengekspos:

getUser
listUsers
searchUsers
queryUsers
Enter fullscreen mode Exit fullscreen mode

Bagi model, semuanya terlihat seperti variasi dari ide yang sama.

Solusinya bukan memperpanjang semua deskripsi. Pilih tool yang benar-benar dibutuhkan agen dan keluarkan sisanya dari daftar. Kumpulan tool yang dikurasi selalu lebih baik daripada kumpulan yang lengkap tetapi ambigu.

2. Kumpulan admin

Tool baca dan destruktif sering berdampingan dengan nada yang sama:

getInvoice
voidInvoice
deleteInvoice
Enter fullscreen mode Exit fullscreen mode

Tambahkan konsekuensi ke deskripsi:

  • Apakah data dihapus?
  • Apakah tindakan dapat dibatalkan?
  • Apakah persetujuan diperlukan?

Tetap enforce aturan di executor. Jangan hanya mengandalkan model atau deskripsi. Gunakan pendekatan berlapis seperti pada panduan mencegah agen menghancurkan API.

3. Kumpulan legacy

Jika dua endpoint melakukan pekerjaan yang sama dan salah satunya sudah usang, generator tool dapat tetap mengeluarkan keduanya. Akibatnya, model bisa memilih endpoint lama.

Hapus operasi usang dari tool yang dihasilkan. Jika belum bisa, letakkan peringatan di awal deskripsi:

Tidak digunakan lagi. Gunakan createOrderV2 sebagai gantinya.
Enter fullscreen mode Exit fullscreen mode

Model cenderung lebih memperhatikan peringatan di awal daripada yang ditulis di akhir.

Deskripsi adalah konfigurasi bersama

Jika deskripsi tool memengaruhi perilaku agen, deskripsi tersebut harus diperlakukan sebagai artefak bersama dan ditinjau seperti interface lainnya.

Jangan menyimpannya hanya di file lokal milik orang yang pertama kali menyiapkan agen. Perubahan deskripsi harus dapat ditinjau, dilacak, dan digunakan oleh seluruh tim.

Platform seperti Sharkly memodelkan agen sebagai konfigurasi tersimpan yang mencakup instruksi, Runtime, Keterampilan, dan repositori. Ketika konfigurasi dibagikan di Ruang, perubahan tool tidak lagi menjadi perbedaan lokal yang sulit dilacak.

Gunakan kata-kata yang dipakai pengguna

Kesenjangan kosakata adalah penyebab yang sangat umum:

Istilah API Istilah pengguna
subscription plan, membership, paket, billing
deactivate cancel, close, turn off
refund kembalikan uang, batalkan pembayaran

Kumpulkan frasa nyata dari:

  • Tiket dukungan
  • Log pencarian
  • Transkrip eksekusi agen yang gagal

Masukkan frasa tersebut ke deskripsi tool yang seharusnya cocok. Perubahan kecil ini sering memberi peningkatan lebih besar daripada tuning skema.

Jika agen tidak memilih tool dan menjawab dari pengetahuannya sendiri, masalahnya bisa berupa kosakata—bukan penalaran. Bahasa pengguna tidak pernah tumpang tindih dengan teks definisi tool.

Daftar periksa tool

  • [ ] Nama mengikuti satu konvensi kataKerjaKataBenda.
  • [ ] Nama menyebutkan objek yang spesifik.
  • [ ] Deskripsi menjelaskan tindakan, perubahan, kondisi penggunaan, dan batasan.
  • [ ] Tool yang tumpang tindih menyebutkan alternatifnya.
  • [ ] Deskripsi menggunakan kosakata pengguna.
  • [ ] Tindakan destruktif dan irreversible dijelaskan.
  • [ ] Enum digunakan untuk setiap set nilai tertutup.
  • [ ] Unit dan format ditulis di nama atau deskripsi parameter.
  • [ ] Contoh format diberikan untuk tanggal, ID, dan nilai ambigu.
  • [ ] Parameter wajib sesuai dengan validasi API.
  • [ ] Tool yang bergantung menyebutkan prasyarat.
  • [ ] Suite pemilihan berjalan di CI terhadap mock.

Model mencocokkan pola berdasarkan teks yang Anda tulis. Ketika model salah memilih, periksa deskripsi tool terlebih dahulu—biasanya di situlah perbaikan paling efektif dapat dilakukan.

Unduh Apidog untuk mengelola spesifikasi, mock, dan pengujian dalam satu proyek.

Pertanyaan yang sering diajukan

Berapa panjang deskripsi tool?

Cukup panjang untuk menghilangkan ambiguitas—biasanya dua hingga lima kalimat. Deskripsi memakan context window, jadi gunakan ruang lebih banyak untuk tool yang saling berdekatan dan lebih sedikit untuk tool yang sudah jelas.

Haruskah saya menyertakan contoh?

Ya, terutama untuk format dan unit. Contoh dapat menghilangkan seluruh kelas kesalahan. Hindari contoh penggunaan yang panjang karena jarang meningkatkan pemilihan tool.

Lebih baik banyak tool sempit atau beberapa tool fleksibel?

Tool yang sempit biasanya lebih andal karena masing-masing melakukan satu hal. Namun, puluhan tool juga dapat membuat daftar menjadi sulit dipilih. Gunakan filtering atau retrieval seperti pada panduan menghasilkan tool agen dari OpenAPI.

Bisakah saya memperbaiki pemilihan lewat system prompt?

Sebagian. Ini masuk akal sebagai solusi sementara untuk satu atau dua kebingungan yang diketahui, tetapi tidak berskala. System prompt dibagikan ke semua tool, sedangkan deskripsi dapat menyertakan konteks tepat di tool yang membutuhkannya.

Bagaimana jika model terus menciptakan nilai parameter?

Batasi tipe, tambahkan enum, dan jelaskan bahwa nilai harus berasal dari panggilan sebelumnya. Jika masalah berlanjut, validasi input di wrapper dan kembalikan error yang mencantumkan nilai yang diizinkan.

Apakah aturan ini juga berlaku untuk server MCP?

Ya. Server MCP mengekspos nama, deskripsi, dan skema dengan cara yang serupa. Prinsip penamaan dan penulisan deskripsi yang sama tetap berlaku. Baca penjelasan tentang apa itu MCP untuk memahami protokolnya.

Top comments (0)