Tool Retrieval تو Gemini API: ابزارها رو فقط وقتی لازمه لود کن
خلاصهٔ کاملتر
گوگل قابلیت Tool Retrieval رو بهصورت preview به Interactions API در Gemini اضافه کرده. مشکلی که حل میکنه اینه: وقتی یه ایجنت به دهها یا صدها ابزار وصله، فرستادن parameter schema (یعنی توضیح دقیق ورودیهای هر تابع) برای همهشون تو هر درخواست، توکن ورودی رو زیاد میکنه، کندش میکنه و با بلندتر شدن لیست، دقت مدل تو انتخاب ابزار درست هم پایین میاد.
برای روشن کردنش کافیه یه ابزار tool_search به درخواست اضافه کنی و روی ابزارهایی که میخوای کنار بمونن defer_loading: true بذاری. مدل هنوز اسم و توضیح همهی ابزارها رو میبینه ولی schemaها تو context نیستن. وقتی ابزاری لازم شد، مدل اسمش رو درخواست میکنه، API schema رو لود میکنه و مدل تابع رو صدا میزنه، همهش داخل همون یه درخواست:
tools = [
{"type": "tool_search"},
{
"type": "function",
"name": "issue_refund",
"defer_loading": True,
},
]هر سه مرحله (جستجو، نتیجهی جستجو و function_call) تو interaction.steps ثبت میشن، پس موقع دیباگ میشه دید مدل کدوم ابزارها رو در نظر گرفته. لازم نیست هیچ ایندکسی بسازی یا هاست کنی، چون جستجو سمت سرور گوگل انجام میشه. گوگل پیشنهاد میده ابزارهای پرکاربرد رو از اول لود کنی و بقیه رو defer کنی. این قابلیت با prefix caching هم سازگاره، چون schemaهای لودشده بعداً تو مکالمه اضافه میشن و اول پرامپت ثابت میمونه. روی سرورهای MCP ریموت هم کار میکنه: اگه روی یه ابزار mcp_server فلگ defer بذاری، همهی ابزارهای اون سرور بهصورت on-demand لود میشن.
اگه خودت registry ابزار یا فیلتر دسترسی برای هر کاربر داری، میتونی tool_search رو با "execution": "client" تعریف کنی تا جستجو سمت اپ خودت انجام بشه. این حالت برای هر جستجو یه رفتوبرگشت اضافه داره، ولی در عوض ابزارها لازم نیست از اول تعریف بشن و میشه وسط مکالمه ابزار جدید اضافه کرد، مثلاً وقتی کاربر یه integration تازه وصل میکنه.
Tool Retrieval هزینهی جداگونه نداره و توکنها با نرخ عادی مدل حساب میشن. روشن کردن tool_search یه بلوک کوچیک و ثابت توکن ورودی اضافه میکنه و هر schemaیی که لود بشه تا آخر مکالمه بهعنوان ورودی حساب میشه. یعنی صرفهجویی وقتیه که schemaهایی که هیچوقت لود نمیشن از اونایی که لود میشن بیشتر باشن، که برای کتابخونههای بزرگ معمولاً همینطوره. گوگل توصیه میکنه با ترافیک واقعی خودت اندازهش بگیری.
نکات کلیدی:
- Tool Retrieval فعلاً بهصورت preview و فقط تو Interactions API در دسترسه.
- با defer_loading: true schema ابزار فقط موقع نیاز لود میشه.
- حالت client-side با "execution": "client" یه رفتوبرگشت اضافه برای هر جستجو داره.
- هزینهی جدا نداره و schemaهای لودشده مثل توکن ورودی عادی حساب میشن.
- با Gemini 3.6 به بعد، از جمله همهی مدلهای Gemini 4، کار میکنه.




