aihariini – Tool Retrieval di Gemini API membantu agen AI memilih alat yang dibutuhkan tanpa harus memuat seluruh rincian alat sejak awal. Fitur ini menarik buat kamu yang membangun agen dengan banyak fungsi dan ingin menjaga alur kerjanya tetap efisien.

Tool Retrieval Gemini API

Fitur ini tersedia dalam tahap preview di Gemini Interactions API. Kamu bisa mulai mencobanya dengan menambahkan tool_search dan mengatur tool yang ingin ditunda pemuatannya.

Kenali masalah yang diselesaikan Tool Retrieval

Agen AI adalah sistem yang bisa memakai model untuk menjalankan tugas dengan bantuan tool, seperti fungsi dalam aplikasi. Semakin banyak tugas yang ditangani, semakin panjang pula daftar tool yang mungkin perlu dikenali agen.

Setiap tool punya parameter schema, yaitu rincian tentang masukan yang dibutuhkan agar fungsi bisa dipanggil dengan benar. Jika agen terhubung ke puluhan atau ratusan tool, mengirim semua schema pada setiap permintaan bisa menambah token input, memperlambat respons, dan menurunkan akurasi pemilihan tool.

Tool Retrieval menawarkan pendekatan yang lebih hemat: library tool tetap tersedia, tetapi schema hanya dimuat saat diperlukan. Nama dan deskripsi tool yang ditunda tetap terlihat oleh model, sehingga model masih bisa menemukan fungsi yang relevan.

Langkah mengaktifkan Tool Retrieval

Sebelum mulai, pastikan aplikasi kamu memakai Interactions API dan model yang didukung. Tool Retrieval tersedia untuk Gemini 3.6 dan model setelahnya, termasuk semua model Gemini 4.

Untuk alur pencarian yang dijalankan Gemini di server, kamu tidak perlu membuat atau meng-host indeks pencarian sendiri. Ikuti urutan berikut untuk menyiapkan request:

  1. Periksa daftar tool agen. Kelompokkan fungsi yang sering dipakai dan fungsi yang hanya dibutuhkan untuk tugas tertentu.
  2. Tambahkan tool_search. Sertakan tool ini dalam request agar model bisa mencari tool yang schema-nya ditunda.
  3. Tandai tool yang ingin ditunda. Atur defer_loading: true pada setiap tool pilihan. Nama dan deskripsinya tetap bisa dilihat model, tetapi schema lengkapnya belum dimasukkan ke konteks.
  4. Biarkan tool yang sering dipakai tetap siap. Kamu tidak harus menunda seluruh library; tool yang rutin digunakan bisa tetap dimuat di depan.
  5. Uji dengan tugas yang relevan. Berikan permintaan yang membutuhkan tool tertunda, lalu periksa apakah agen menemukan dan memanggil fungsi yang tepat.

Mulailah dari fungsi yang jarang digunakan agar kamu lebih mudah membandingkan alur sebelum dan sesudah pengaturan. Perhatikan juga apakah deskripsi setiap tool cukup jelas untuk membantu model membedakan kegunaannya.

Pahami alur pencarian sampai fungsi dijalankan

Ketika sebuah tugas membutuhkan tool tertunda, model meminta tool itu berdasarkan namanya. API lalu memuat schema lengkap, setelah itu model bisa memanggil fungsinya dalam request yang sama.

Misalnya, pada tugas pengembalian dana, model mencari issue_refund, API memuat schema fungsi itu, lalu model mengeluarkan function_call atau permintaan pemanggilan fungsi. Ketiga langkah tersebut muncul di interaction.steps, sehingga kamu bisa memeriksa urutannya.

Sesudah pemanggilan fungsi, alurnya kembali seperti function calling biasa: kode aplikasimu menjalankan proses refund dan mengembalikan function_result sebagai hasilnya. Tool Retrieval membantu menemukan dan memuat schema; aplikasi tetap bertanggung jawab menjalankan fungsinya.

Baca Juga :

Atur tool dan caching agar lebih efisien

Strategi campuran sering lebih masuk akal daripada menunda semua tool. Simpan fungsi yang hampir selalu diperlukan dalam konteks awal, lalu tunda fungsi khusus yang hanya muncul pada sebagian tugas.

Pembagian ini membantu kamu memanfaatkan tujuan utama Tool Retrieval: mengurangi rincian yang dikirim di awal tanpa membuat agen kehilangan akses ke library yang lebih luas. Saat menguji, periksa pemilihan tool dan waktu respons untuk tugas yang berbeda, bukan hanya satu contoh.

Fitur ini juga kompatibel dengan prefix caching, yaitu penggunaan kembali bagian awal prompt yang sama. Karena schema tertunda berada di luar bagian awal prompt, cached prefix bisa tetap sama dari satu giliran percakapan ke giliran berikutnya.

Manfaatkan MCP atau pencarian di aplikasi

Jika memakai remote MCP server, kamu juga bisa menunda pemuatan tool yang disediakan server itu. MCP adalah cara menghubungkan model dengan sumber kemampuan eksternal; atur defer_loading: true pada tool mcp_server agar semua tool yang diekspos server dimuat saat diperlukan.

Untuk kebutuhan yang lebih khusus, pencarian bisa dijalankan di sisi aplikasi. Caranya, deklarasikan tool_search dengan "execution": "client" dan tentukan sendiri parameter pencariannya. Opsi ini relevan kalau kamu sudah punya registri tool, indeks embedding, atau penyaring izin per pengguna.

Perbedaannya, aplikasi melakukan lookup sendiri sehingga ada satu perjalanan tambahan antara aplikasi dan API untuk setiap pencarian. Sebagai gantinya, tool tidak harus dideklarasikan sejak awal dan tool baru bisa diekspos di tengah percakapan.

Pantau token dan pilih alur sesuai kebutuhan

Tool Retrieval tidak memiliki biaya terpisah, tetapi token input dan output tetap ditagih sesuai tarif standar model yang kamu pakai. Mengaktifkan tool_search menambahkan blok kecil token input yang tetap, sedangkan setiap schema yang dimuat dihitung sebagai input untuk sisa percakapan.

Karena itu, jangan menilai efisiensi hanya dari jumlah tool yang ditunda. Perhatikan juga tool mana yang akhirnya dimuat dalam percakapan dan apakah fungsi yang sering dipakai lebih cocok tersedia sejak awal.

Untuk mulai, pilih satu alur agen yang library-nya sudah cukup besar, rapikan nama serta deskripsi tool, lalu uji beberapa jenis permintaan. Periksa interaction.steps dan hasil fungsi, kemudian sesuaikan pembagian tool berdasarkan kebutuhan aplikasimu.