الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.
بعض الـ providers يشغّلون tools بنفسهم، داخل طلب الـ model نفسه. أشهرها عند OpenAI: web search وcode interpreter وfile search. ضعها في tools بجانب الـ tools التي تعرّفها أنت. الـ provider هو الذي يشغّلها، والـ run يبلّغ عن كل call في الـ events، ويحتفظ بها في الـ transcript (سجل الرسائل)، ويحسبها في الـ usage.
الـ SDK لا ينفّذ أي hosted tool أبدًا. يرسلها مع كل model call في الـ run ويبلّغ عمّا فعله الـ provider. بادئة vendor/ في الـ model هي التي تختار الـ provider. مع OpenRouter استخدم openrouter/<vendor>/<model> (مثل openrouter/openai/gpt-4o-mini).

الـ helpers

isHostedTool(value) تفرّق بين الـ hosted tool والـ tool المحلية. اسم كل helper هو نفس الاسم الذي يستخدمه الـ model والـ events وusage.hostedToolCalls. إذا كتبت tools على شكل record، فيجب أن يكون مفتاح الـ hosted tool هو اسمها (tools: { web_search: webSearch(), lookup }). hosted tool باسم tool أخرى يرمي الخطأ LOUSHO_CONFIG_INVALID عند إنشاء الـ agent. كل provider يستخدم الخيارات التي يدعمها ويتجاهل الباقي مع console.warn واحدة. OpenAI يأخذ searchContextSize وuserLocation وallowedDomains (بدون maxUses وبدون blockedDomains). Anthropic يأخذ maxUses وallowedDomains وblockedDomains وuserLocation (بدون searchContextSize؛ والـ code execution عنده بلا container). OpenRouter يأخذ maxUses وallowedDomains وblockedDomains (يُرسلها باسم excluded_domains عنده) وsearchContextSize (بدون userLocation).

أي provider يشغّل أي tool

الـ hosted tools تحتاج ai 6 أو 7. الاستثناء الوحيد: web search في OpenRouter يعمل على ai 4 أيضًا. مع ai 4 (ومعه @ai-sdk/openai بإصدار 0.0.x أو 1.x) يُرفض كل hosted tool آخر. في OpenAI الـ model هو الـ Responses API model، وهو ما تعطيه @ai-sdk/openai من الإصدار 2 فصاعدًا. في Anthropic تستخدم الـ helpers أحدث server tool مؤرَّخة تصدّرها نسخة @ai-sdk/anthropic المثبّتة لديك: webSearch() تأخذ أحدث tools.webSearch_*()، وcodeInterpreter() تأخذ أحدث tools.codeExecution_*() (Anthropic يسمّيها code_execution؛ والـ SDK يبقي الاسم code_interpreter في الـ events وفي usage.hostedToolCalls على كل الـ providers). الحزمة التي لا تحتوي أيًّا منها تُرفض مع ذكر التوليفة التي تعمل. ولأي server tool أخرى في Anthropic (مثل web fetch) استخدم hostedTool('web_fetch', anthropic.tools.webFetch_20260318()). في OpenRouter، webSearch() تضيف الـ server tool الخاصة بـ OpenRouter، وهي openrouter:web_search، إلى الطلب. يجري البحث على جهة OpenRouter لأي model. OpenRouter هو من يختار محرك البحث: بحث الـ model نفسه إن كان عنده، وإلا Exa. ويحاسبك على كل بحث فوق الـ tokens بالأسعار الموجودة في صفحة أسعار OpenRouter. راجع دليل web search لتفاصيل المحركات. ولأن السيرفر ينفّذ البحث داخل الطلب، الـ model لا يبلّغ عن أي tool call. بدلها يبلّغ الـ SDK عن hosted call واحدة لكل model step بحث فيها، ويقرأها من ردّ OpenRouter: name: 'web_search'، وargs فارغة، والروابط المستشهد بها من url_citation annotations تصبح sources، وresult: { requests } إذا بلّغ OpenRouter عن usage.server_tool_use.web_search_requests (وإلا result تكون {}؛ الاختبار الحي لم يستلم عددًا). الاستعلام الذي بحث عنه الـ model لا يُبلَّغ عنه. أي توليفة غير مدعومة ترفض الـ run قبل أول model call بخطأ LOUSHO_HOSTED_TOOL_UNSUPPORTED يذكر الـ provider والـ tool وما الذي سيشتغل. الـ LLMProvider المخصّص يعلن عمّا يستطيع إرساله عبر supportsHostedTool(type) — قيمة type هي 'web_search' أو 'code_interpreter' أو 'file_search' أو 'custom' لـ hostedTool() — ويستلم الـ tools في GenerateOptions.hostedTools. الـ provider الذي لا يملك هذه الدالة لا يدعم أي hosted tool. وwithRetry() وwithFallback() تسألان الـ provider المغلَّف (الأول).

أي provider tool من AI SDK: hostedTool()

hostedTool(name, tool) ترسل كائن الـ provider tool الذي بنيته بحزمة الـ provider كما هو، بدون تغيير، على ai 6 أو 7. تعمل مع الـ providers المدمجة ومع أي model من AI SDK مغلَّف بـ fromAiSdk():
استخدم اسم الـ tool كما توثّقه حزمة الـ provider.

الـ events

الـ hosted call يُبلَّغ عنها مثل tool call، مع executedBy: 'provider' في tool.start وtool.done وtool.error:
إذا كان الـ model call بـ streaming، تصل الـ events لحظة يُبلغ الـ provider عن الـ call. وإذا كان بدون streaming، تصل بعد الـ call، بترتيب الـ calls، وقبل نصّه. tool.done.result محدودة بـ 20,000 حرف من JSON؛ النتيجة الأطول تصبح نص JSON مقصوصًا ينتهي بـ ... [truncated N characters]. وفي tool.error تكون error.name هي 'HostedToolError' مع رسالة الـ provider. وبث واجهة AI SDK (toUIMessageStream()) يعلّم أجزاء الـ tool هذه بـ providerExecuted: true. في الـ traces، الـ chat span الخاص بـ model call يحمل lousho.hosted_tool_calls (أسماء الـ tools التي شغّلها الـ provider فيه). لا يوجد execute_tool span لها، لأن الـ SDK لم ينفّذ شيئًا.

الـ transcript والـ replay

رسالة الـ assistant في الـ step تحصل على metadata.hostedToolCalls: لكل call قيم id وname وargs وresult (بنفس الحد أعلاه) وisError وsources للروابط التي استشهد بها الـ provider بعدها. تجدها في result.messages. في الـ calls اللاحقة يُرجَع للـ model نص الـ assistant فقط، ولا تُرجَع كتل الـ tools الخاصة بالـ provider أبدًا. هذا يعمل مع كل provider وكل model. الثمن: الـ citations من الدورات السابقة لا تُعاد للـ model.

الـ usage والتكلفة

result.usage.hostedToolCalls (وusage.hostedToolCalls في run.done) تحسب الـ calls لكل اسم tool، مثل { web_search: 2 }. الـ calls الخاصة بالـ sub-agent تُضاف إلى calls الـ lead. الـ tokens التي تضيفها الـ hosted tool (نتائج البحث التي يقرأها الـ model، ومخرجات الكود) داخلة في عدّادات الـ tokens التي يبلّغ عنها الـ provider. costUsd يغطي الـ tokens فقط. رسوم كل call للـ hosted tools (بحث ويب أو session (جلسة) لـ code interpreter) يحاسب عليها الـ provider ولا تدخل فيها. راجع أسعار الـ provider واستخدم الأعداد أعلاه.

الموافقات والصلاحيات

الـ SDK لا يستطيع ضبط شيء لا ينفّذه. الـ hosted tool تعمل داخل طلب الـ provider، فلا تراها أي قاعدة صلاحيات، ولا guardrail للـ tools، ولا needsApproval، ولا hook مثل preToolCall / postToolCall أو onToolCall. ولا يمكن إيقاف hosted tool لطلب approval (موافقة). إذا كان الـ run ممنوعًا من البحث أو تنفيذ كود دون إنسان، اترك الـ tool خارج tools، أو اختر الـ tools لكل run بدالة:
أوضاع الصلاحيات أيضًا لا تستطيع رفض hosted call، لذلك دورها أنها تقرر أي hosted tools تُرسل مع كل model call: الـ code interpreter ينفّذ كودًا، وhostedTool() هي tool لا يعرف عنها الـ SDK شيئًا، لذلك وضع plan يتعامل مع الاثنين كـ tools لها side effects. الوضع يُقرأ قبل كل model call، فأي تبديل (session.setPermissionMode() أو وضع معطى كدالة) يسري من الـ call التالي. ولا يُكتب إدخال permission.decision لأي hosted tool استُبعدت: ما حصل أي call. الـ sub-agents لا ترث الـ hosted tools الخاصة بالـ lead؛ أعطِ كل sub-agent أدواته في tools. الـ run الذي يُستأنف من checkpoint أو من approval يرسل نفس الـ hosted tools. والـ agent الذي يستأنف بمجموعة مختلفة يبلّغ عن agent drift.

الاختبار

mockModel يقبل hosted calls في الـ turn ويسجّل hostedTools في كل request، فيستطيع agent لديه hosted tools العمل دون اتصال:

غير مغطّى بعد

لا توجد helpers لـ image generation وcomputer use وhosted MCP وhosted shell؛ مرّر الـ tool من حزمة الـ provider عبر hostedTool() حيث تعمل. وإعادة إرسال كتل الـ tools الخاصة بالـ provider للإبقاء على الـ citations عبر الدورات غير مدعومة.