الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.
agent عنده tools كثيرة (عدة سيرفرات MCP أو toolkit داخلية كبيرة) يرسل تعريف كل tool مع كل استدعاء للـ model. هذا يكلّف input tokens، وبعد حوالي 30 tool يصبح الـ model أسوأ في اختيار الصحيحة. مع tool search، الـ tools المعلَّمة بـ deferLoading تُترَك خارج الطلب. الـ model يحصل على tool مدمجة واحدة هي tool_search، يلاقي الذي يحتاجه بكلمات قليلة، والـ tools التي وجدها تُرسَل من خطوته التالية. البحث يعمل داخل الـ SDK، فيعمل مع كل provider.

متى تستخدمه

  • الـ agent متصل بسيرفرات MCP فيها tools كثيرة، أو عنده tool set كبيرة، ومعظم الـ runs تستخدم منها القليل فقط.
  • تعريفات الـ tools تأخذ حصة واضحة من الـ context window.
مع عدد قليل من الـ tools لا شيء تكسبه: افتراضيًا لا يُطبَّق التأجيل إلا حين تبلغ التعريفات المؤجلة 10% من الـ context window (انظر العتبة).

علّم الـ tools أو السيرفرات بـ deferLoading

علّم tool بعينها بـ defineTool({ deferLoading: true }). بادئة الـ model vendor/ تختار الـ provider؛ ومع OpenRouter استخدم openrouter/<vendor>/<model> (مثل openrouter/openai/gpt-4o-mini).
أو علّم سيرفر MCP كامل: كل tool يسردها تُؤجَّل.
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.