deferLoading تُترَك خارج الطلب. الـ model
يحصل على tool مدمجة واحدة هي tool_search، يلاقي الذي يحتاجه بكلمات
قليلة، والـ tools التي وجدها تُرسَل من خطوته التالية.
البحث يعمل داخل الـ SDK، فيعمل مع كل provider.
متى تستخدمه
- الـ agent متصل بسيرفرات MCP فيها tools كثيرة، أو عنده tool set كبيرة، ومعظم الـ runs تستخدم منها القليل فقط.
- تعريفات الـ tools تأخذ حصة واضحة من الـ context window.
علّم الـ tools أو السيرفرات بـ deferLoading
علّم tool بعينها بـ defineTool({ deferLoading: true }). بادئة الـ model
vendor/ تختار الـ provider؛ ومع OpenRouter استخدم
openrouter/<vendor>/<model> (مثل openrouter/openai/gpt-4o-mini).
deferLoading يعمل بنفس الطريقة في ملفات spec ومجلدات الـ agent
(mcpServers.<name>.deferLoading: true)، ومع connectMcp(): الـ
descriptors التي يرجعها تحمل deferLoading، فتمرير mcp.tools إلى
createAgent({ tools }) يحافظ على التأجيل.
لا تُؤجَّل أبدًا مهما عُلِّمت: load_skill (skills)، وأدوات
الذاكرة، وtask وأدوات مهام الخلفية (sub-agents)،
وask_question، وأدوات transfer_to_<name> الخاصة بـ
handoffs، وtool_search نفسها. أما الـ tools المستضافة
لدى الـ provider فتُرسَل دائمًا.
ما يراه الـ model
حين ينطبق التأجيل، يحتوي أول طلب في الـ run على الـ tools غير المؤجلة معtool_search، ويأخذ الـ system prompt فقرة واحدة: كم tool لم
تُحمَّل، ومن أي سيرفرات MCP جاءت (مع العدد)، وأن عليه استدعاء
tool_search بكلمات قليلة تصف القدرة المطلوبة.
tool_search تأخذ { query: string } وترجع JSON:
loaded يسرد الـ tools التي وجدها هذا البحث (بحد أقصى maxResults)،
وmore يعدّ الـ tools المؤجلة التي لم تُحمَّل بعد. من الخطوة التالية
يتضمن الطلب هذه الـ tools. وحين تُحمَّل كل الـ tools المؤجلة لا تعود
tool_search معروضة.
الـ tool المؤجلة التي يستدعيها الـ model باسمها قبل تحميلها تعمل مثل أي
tool أخرى (الـ approvals والصلاحيات والـ guardrails تنطبق كالمعتاد).
وstream() يبلّغ عن tool_search كزوج عادي tool.start / tool.done.
الترتيب الافتراضي يقارن كلمات الاستعلام باسم كل tool مؤجلة (مقسَّمًا عند
_ و- و__ وحدود camelCase) ووصفها، بلا حساسية لحالة الأحرف. الكلمة
في الاسم تُحسب ثلاثة أضعاف الكلمة في الوصف، وصيغ الجمع تُوحَّد مع المفرد
(statuses تجد status). والكلمة القريبة تأخذ جزءًا من النقاط: من نفس
عائلة الكلمة (sending تجد send)، أو مرادف من جدول صغير مدمج لأفعال
وأسماء الـ tools الشائعة (fetch / get / retrieve، وdelete /
remove، وshare / stock / equity، وvalue / price / quote)،
فالاستعلام share value يجد fetch_equity_quote. الكلمات المطابقة تمامًا
تبقى أعلى من القريبة، والتعادل يُرتَّب بالاسم. نفس الدالة مُصدَّرة باسم
rankToolsByKeywords(query, tools). ويبقى البحث لفظيًا: للبحث الدلالي
الحقيقي مرّر search خاصة بك (مثلًا embeddings).
خيارات toolSearch
createAgent({ toolSearch }) وAgentExecutor.execute({ toolSearch })
يضبطان البحث. التأجيل نفسه يُفعَّل بتعليم الـ tools أو السيرفرات بـ
deferLoading؛ وtoolSearch: false يحمّل كل الـ tools مسبقًا.
LOUSHO_CONFIG_INVALID عند إنشاء الـ agent.
وtool من عندك اسمها tool_search ترمي LOUSHO_CONFIG_INVALID حين يبدأ
run والتأجيل فعّال: غيّر اسمها أو اضبط toolSearch: false.
العتبة
عند بدء الـ run يقدّر الـ SDK عدد الـ tokens في التعريفات المؤجلة (الاسم والوصف والـ JSON Schema لكل tool، عبرestimateTokens() للـ
model الخاص بالـ run). تحت thresholdPercent من الـ context window
تُرسَل كل الـ tools مسبقًا ولا تُضاف tool_search: التعريفات رخيصة،
وخطوة بحث ستكلّف أكثر مما توفّر. هذه نفس قاعدة وضع auto في
Claude Agent SDK.
الاختبار الحي لهذه الميزة (40 tool من سطر واحد على gpt-4o-mini) قاس
157 input token في الاستدعاء الأول مع التأجيل، و892 بدونه.
كيف يبقى التحميل
الـ tools المحمَّلة لا تُخزَّن في أي مكان: تُقرأ من الـ transcript عند كل استدعاء للـ model. الـ tool تُعتبر محمَّلة إذا سمّتها نتيجةtool_search ناجحة في رسائل الـ run. لذلك:
- الاستئناف بعد crash من checkpoint، وتوقف الـ approval واستئنافه، والـ fork، والدورة التالية في الـ session، كلها تبقي الـ tools المحمَّلة.
- الاستئناف لا يبلّغ عن agent drift بسبب التحميل: الـ fingerprint يشمل كل tool، مؤجلة أو لا.
- compaction يقتطع نتيجة
tool_searchيلغي تحميل أدواتها من استدعاء الـ model التالي؛ والـ model يبحث من جديد حين يحتاجها. - هدف الـ handoff يبدأ بلا أي tool محمَّلة، حتى لو كان
عنده نفس الـ tools المؤجلة: لا تُحسب إلا نتائج
tool_searchبعد آخر handoff، وتنطبق أدواتdeferLoadingوإعدادtoolSearchالخاصة بالهدف. أما الـ sub-agent فيشغّل قائمة الـ tools الخاصة به على الـ transcript الخاص به، فلا يرث أبدًا ما حمّله الـ lead.
سيرفرات MCP التي تحتاج تسجيل دخول
سرد tools السيرفر يحتاج اتصالًا، لذا سيرفر معلَّم بـdeferLoading
ويستخدم OAuth ولم يُسجَّل الدخول إليه
يُفشِل الـ run بـ LOUSHO_MCP_AUTH_REQUIRED مثل أي سيرفر آخر. حين
يسجّل المشغّل الدخول تُؤجَّل أدواته كالمعتاد. وأي صلاحية تُسحَب لاحقًا
تحوّل استدعاء tool محمَّلة إلى خطأ LOUSHO_MCP_AUTH_REQUIRED، كما لو
بلا تأجيل.
Prompt caching
قائمة الـ tools تتغير حين تُحمَّل الـ tools. OpenAI يخزّن بادئة الطلب مؤقتًا تلقائيًا، ومع models Claude يضع الـ SDK نقاط cache الخاصة بـ Anthropic (promptCaching: 'auto'). وكلاهما يضع
تعريفات الـ tools في أول البادئة، فالخطوة التي تحمّل tools تفوت الـ cache من
تلك النقطة وتكتب إدخالًا جديدًا. التحميل يحدث بضع مرات في الـ run الواحد على
الأكثر. وإذا كانت الـ runs عندك تعيد استخدام بادئة مخزَّنة طويلة عبر استدعاءات
كثيرة، قارن التكلفة مع toolSearch: false.