الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.
الـ tool هو دالة typed يستطيع الـ model استدعاءها. عرّفه بـ defineTool(): تُستنتج أنواع الوسائط والنتيجة من zod input، وتمر الوسائط على validation قبل أن تعمل execute، ويمكن وضع النتيجة في أي مكان يقبل tools (createAgent({ tools: [...] })، ToolRegistry.register(tool)، AgentBuilder.addTool(tool)).
تترك الأمثلة في هذه الصفحة بعض الأسماء لك: provider هو أي LLMProvider (بدون إنترنت: createMockProvider()).
الـ tools التي يشغّلها الـ provider نفسه (web search، code interpreter، file search) تضعها في قائمة tools نفسها؛ انظر Hosted provider tools. إذا كانت لديك tools كثيرة، فعلّمها بـ deferLoading لكي يجدها الـ model عبر tool_search (tool مدمج) بدلًا من أن يستلم كل التعريفات في كل call؛ انظر Tool search. الـ tools المكتوبة لـ Vercel AI SDK (tool({ description, inputSchema, execute })) تتحوّل بـ fromAiSdkTools({ weather, sendEmail })، ومعها needsApproval؛ انظر الانتقال من AI SDK.

خيارات defineTool()

تفحص defineTool() الاسم والوصف وzod input عند استدعائها، وترمي خطأً يخبرك كيف تصلح القيمة الخاطئة. تسجيل toolين بالاسم نفسه يرمي خطأً يسمّي التعارض. أي خيار غير موجود في الجدول أعلاه يُعتبر خطأً (LOUSHO_CONFIG_INVALID) مع اقتراح، لكي لا يجعل خيارُ أمانٍ مكتوبٌ خطأً tool يعمل بدون approval: requireApproval: true يعطي 'requireApproval' is not a known option (did you mean 'needsApproval'?)، وinputSchema أو parameters يرشدانك إلى input. ويُقبل الـ tool المعرّف إذا أعدته عبر spread (defineTool({ ...tool, execute })). وترفض أيضًا (LOUSHO_CONFIG_INVALID) أي input لا يستطيع أي model تلبيته:
  • يجب أن يكون الجذر object. يرسل الـ providers وسائط الـ tool كـ JSON object، لذلك يُرفض z.string() أو z.array(...) في الجذر. غلّفه: z.object({ value: z.string() }).
  • لا حقول z.date() ولا z.bigint(). يكتب الـ model هناك نص ISO أو رقمًا، وهذه الـ schemas ترفض الاثنين، فيفشل كل call. استخدم z.coerce.date() (أو z.iso.datetime() إذا أردت الإبقاء على النص) وz.coerce.bigint() (أو z.number().int()).
الـ tool المعرّف هو ToolDescriptor عادي: يحمل الـ schema في inputSchema (الـ schema نفسها الموجودة في input) ودالة execute مباشرة. أما حقل .tool (كائن { description, parameters, execute } من ai v4) فقديم: ما زال مقبولًا للتوافق، ويُقرأ حقلًا حقلًا — الـ descriptor المكتوب يدويًا بدون inputSchema يستخدم tool.parameters كـ fallback، والذي بدون execute يستخدم tool.execute كـ fallback، كلٌّ على حدة.

ماذا يحدث عندما يستدعي الـ model أداة (tool)

  • الـ validation أولًا. تُحلَّل وسائط الـ model بـ inputSchema (تُطبَّق الـ defaults والـ coercions والـ transforms) قبل أن تراها الـ hooks وneedsApproval وexecute. الوسائط التي لا تطابق لا تصل إلى execute أبدًا: يستلم الـ model نتيجة ToolArgumentsValidationError منظّمة ويستطيع إجراء retry.
  • الأخطاء نتائج. الـ tool الذي يرمي خطأً يعطي الـ model { error, toolName, message, kind } (بدون stack trace) ويستمر الـ run. انظر الأخطاء.
  • Calls متوازية. تعمل عدة calls في model turn واحد بالتوازي؛ حدّها بـ toolConcurrency (1 للتسلسل الكامل). تصل النتائج إلى الـ transcript بترتيب calls الـ model. انظر الـ tool calls المتوازية.
  • حد الحجم. النتيجة التي يتجاوز طول الـ JSON الخاص بها maxToolResultChars (createAgent({ maxToolResultChars })، الافتراضي 50_000 حرف، أي نحو 12k token) تصل إلى الـ model، وإلى الـ transcript، كبدايتها ونهايتها مع علامة تذكر عدد الأحرف المحذوفة. Infinity تعطّل الحد. تستلم onToolResult والـ hooks وأحداث tool.done النتيجة كاملة.
  • الإلغاء. يصل الـ AbortSignal الخاص بالـ run إلى كل call كـ ctx.abortSignal، فيستطيع العمل الطويل أن يتوقف مبكرًا.
  • التقدّم. execute المكتوبة كـ async function* تبث snapshots من مخرجاتها أثناء عملها؛ وآخر snapshot هو النتيجة. انظر Streaming للنتائج الجزئية.
  • Calls كثيرة في خطوة واحدة. مع createAgent({ codeMode }) يستطيع الـ model أيضًا استدعاء tools من برنامج JavaScript قصير (run_code)، ويمر كل call بالفحوص نفسها. انظر Code mode.
  • Retry بعد crash. مع durable execution قد يعمل الـ tool أكثر من مرة عبر crash؛ استخدم ctx.toolCallId كـ idempotency key. انظر Durable execution.

سياق execute

تستلم execute(args, ctx) دائمًا وسيطًا ثانيًا حقيقيًا، نوعه ToolExecutionContext (exported من جذر الحزمة؛ ويحل محل ToolExecutionOptions الخاص بـ ai SDK)، في كل مسار يشغّل tool: الحلقة الرئيسية، والـ call الذي يعمل بعد approval، والـ tools التي تعمل في sandbox (sandboxExecute(args, sandbox, ctx))، وnode استدعاء الـ tool في flow. الدالة sandboxExecute(args, sandbox) التي تتجاهل الوسيط الثالث تظل تعمل.

الأخطاء

أي طريقة يفشل بها tool call تصل إلى الـ model بالنتيجة نفسها، لذلك يكفي فحص واحد في كل الحالات (ومنها الـ call الذي يعمل بعد approval):
  • error: اسم الخطأ (TypeError، ToolArgumentsValidationError، …)، أو الاسم الافتراضي للـ kind عندما لا يكون الفشل خطأً مرميًا.
  • toolName وmessage: الرسالة فقط، بلا stack أبدًا، بحد أقصى 2,000 حرف (... (truncated) علامة القص).
  • kind: سبب فشل الـ call.
  • بعض الأنواع تضيف حقولًا: issues لـ validation، note لـ rejected، reason لـ denied.
رسالة الـ transcript تحمل isError: true؛ وترى أحداث tool-result وonToolResult وhooks الـ postToolCall وأحداث tool.error الـ call فاشلًا. إخفاء نص الاستثناء. تصل رسالة الخطأ المرمي إلى الـ model كما هي، فـ new Error('DB password=hunter2 connection refused') يصله حرفيًا. مرّر toolErrorMessage إلى createAgent لكي تستبدل نص أخطاء execution:
يصبح النص message في النتيجة أعلاه (ويظل الـ kind هو execution). يصل النص نفسه إلى أحداث tool.error وonToolResult وhooks الـ postToolCall، فلا يحمل الـ stream الذي يصل إلى العميل النص الأصلي أبدًا؛ دالتك وحدها ترى الخطأ المرمي. ترثه الـ sub-agents. لا يمس أخطاء validation (لأنها تصف وسائط الـ model الخاطئة نفسها) ولا الأنواع الأخرى. إذا رمت الدالة خطأً أو أرجعت شيئًا ليس نصًا، تصبح الرسالة The tool failed. ويستمر الـ run. وبدون الخيار، لا يتغير شيء. الـ validation الخاصة بالوسائط. تُحلَّل وسائط الـ model بـ zod inputSchema الخاصة بالـ tool (وللـ descriptor القديم، tool.parameters) قبل أن يعمل الـ tool، لذلك تستلم hooks ما قبل الـ tool وneedsApproval وexecute كلها القيمة المحلَّلة (parsed). الـ tools التي لا تملك zod schema تمر وسائطها كما هي. إذا لم تطابق الوسائط، لا تُستدعى execute وتُتخطّى hooks الـ preToolCall، لأنه لا يوجد call صالح. يستلم الـ model نتيجة validation يستطيع إجراء retry بناءً عليها:
ToolArgumentsValidationError (مع مصفوفة issues typed) exported من جذر الحزمة. تبني toolErrorResult({ toolName, error, kind?, toolCallId?, details? }) هذه النتيجة؛ استخدمها في الـ wrappers الخاصة بك لكي تُخرج الشكل نفسه. يستطيع الخطأ المرمي اختيار الـ kind الخاص به بحمل خاصية toolErrorKind. أما الخطأ الذي يرث PropagatingToolError فليس نتيجة: إنه يوقف الـ run.

الـ calls الفاشلة في النتيجة

يرى الـ model كل call فاشل وقد يجيب مع ذلك كأنه نجح، وينهي الـ run بـ finishReason: 'stop'. يعدّ result.toolErrors الـ tool calls في الـ run التي نتيجتها خطأ (أي kind مما سبق ما عدا not-run)؛ ويغيب عندما لا يفشل شيء. يعدّ فقط calls الـ run نفسه: الـ calls التي فشلت داخل الـ sub-agents التابعة له تُعدّ في result.usage.delegated.toolErrors. افحصه قبل أن تثق في text، أو ضع له حدًا بـ limits.maxToolErrors: بمجرد أن يفشل هذا العدد من الـ calls، يتوقف الـ run قبل الـ model call التالي بـ finishReason: 'budget-exceeded' وتكون قيمة result.budget.limit هي 'maxToolErrors' (أو يرفض بـ BudgetExceededError مع onExceeded: 'throw'، انظر الميزانيات).

Tools مدمجة

تُمرَّر الـ descriptors المدمجة keyed بالاسم الذي يستخدمه الـ agent: createAgent({ tools: { current_date: currentDateTool } }). تشير ملفات الـ spec إلى http وweb-fetch وcurrent-date وday-name بالاسم (انظر الإعدادات). كيف ترفض http_request وweb_fetch الوجهات الخاصة: يُفحص الـ host المكتوب كـ IP صريح قبل الطلب؛ ويُحَل اسم الـ host مرة واحدة عند فتح الاتصال، ويُفحص كل عنوان ينتج عنه (loopback، RFC 1918، link-local ومنه عنوان cloud metadata، CGNAT، نطاقات multicast والمحجوزة، IPv4-mapped IPv6، NAT64 و6to4)، ويتصل الـ socket بالعنوان الذي فُحص. تُتبع الـ redirects يدويًا ويُفحص كل hop بالطريقة نفسها. والاسم الذي يُجري DNS rebinding — يجيب بعنوان عام أولًا ثم بعنوان خاص — لا يجد lookup ثانيًا يجيب فيه. وعندما تعمل http_request عبر sandbox، يُحَل الـ host ويُفحص في عملية الـ agent، وتتصل العملية داخل الـ sandbox بالعنوان نفسه. تأخذ الأداتان allowPrivate (أنماط hosts مثل intranet.example أو *.corp.example) للـ hosts التي قد تُحَل إلى عناوين خاصة. تأخذ web_fetch القيمة { url } (http: أو https:، بدون user:password@) وتُرجع { url, finalUrl, status, contentType, content, truncated }. ترسل GET فقط، بلا body ولا cookies ولا headers يختارها المستدعي. يتحول الـ HTML إلى نص عادي (تُزال الـ scripts والـ styles وما شابهها، وكل عنصر block في سطر، وروابط الـ URL بين قوسين، وتُفك الـ entities)؛ ويُرجَع JSON وtext/* كما أُرسلا؛ أما الأنواع الأخرى (صور، PDF، binaries) فتُرجع ملاحظة بدلًا من المحتوى. يُرجَع رد 4xx أو 5xx مع الـ body الخاص به ولا يُرمى كخطأ، لكي يقرأ الـ model صفحة الخطأ. الرفض والـ timeouts وكثرة الـ redirects والـ URLs الخاطئة هي tool errors تسمّي الـ host. الصفحة input غير موثوق: يخبر وصف الـ tool الـ model بذلك، وreadOnlyHint وopenWorldHint مضبوطان. خيارات createWebFetchTool() (البادئة vendor/ في الـ model هي التي تختار الـ provider؛ مع OpenRouter استخدم openrouter/<vendor>/<model> مثل openrouter/openai/gpt-4o-mini):
لكل createWebFetchTool() connection pool خاصة بها، تبقى ما دامت الـ tool موجودة وتُحرَّر معها بالـ garbage collection (لا توجد دالة close). web_fetch غير موجودة في بناء Cloudflare Worker، وhttp_request الخاصة بالـ Worker هي tool مختلفة تصل فقط إلى أسماء الـ hosts المدرجة في binding LOUSHO_HTTP_ALLOW؛ انظر Cloudflare Workers.

Todo tools

تعطي createTodoTools(options?) الـ agents طويلة العمل plan تتبعه: todo_write تستبدل القائمة كلها (عناصر { id?, content, status }، والحالة pending | in_progress | completed، بحد أقصى عنصر in_progress واحد) وتُرجع القائمة مع الأعداد؛ وtodo_read تُرجعها. تُعيَّن الـ ids تلقائيًا وتظل ثابتة عندما تكرر كتابة لاحقة محتوى عنصر. القوائم غير الصالحة (مثل in_progress مرتين) تصل إلى الـ model كـ tool error منظّم لكي يُجري retry. تعيش القائمة في الذاكرة لكل call؛ مرّر store ({ get, set }) لكي تحفظها، وonChange لكي تحدّث UI. كل todo_write ناجحة تُصدر أيضًا حدث stream todo.updated بالقائمة الجديدة وأعدادها (انظر Stream events)، وروابط React وVue وSvelte تحوّله إلى useTodos() / loushoTodos()، فتعرض الـ UI الخطة مباشرة بدون onChange.

متقدم: ToolRegistry

تبني createAgent() registry لك؛ املأ واحدًا بنفسك فقط مع AgentExecutor.execute() (انظر executor API) أو لكي تشارك tools بين agents: register(tool) لناتج defineTool()، وregister(name, descriptor) لـ ToolDescriptor خام (tool مدمجة، أو tool من MCP، أو tool() جاهزة من ai SDK)، وregisterMany() لـ record من descriptors أو مصفوفة من tools معرّفة.
مرّره في toolRegistry إلى AgentExecutor.execute()؛ وتسمّي خريطة tools في إعداد الـ agent الـ tools التي يستطيع استخدامها.

Streaming للنتائج الجزئية

الـ tool الطويلة (تبني تقريرًا، أو تبحث في مصادر كثيرة) تستطيع عرض التقدم أثناء عملها: اكتب execute كـ async function*. كل yield هو snapshot كامل للمخرجات حتى تلك اللحظة، يحل محل ما قبله، ويصل إلى أحداث الـ run كـ tool.partial (انظر Stream events). آخر قيمة تُمرَّر بـ yield هي نتيجة الـ tool: يستلمها الـ model، وهي result الخاصة بالـ call في tool.done، لذلك يظهر الـ snapshot الأخير مرتين (آخر tool.partial وفي tool.done). تُتجاهل قيمة return؛ والـ generator الذي لا يمرّر شيئًا نتيجته null، وكذلك أي tool يُرجع undefined: يرى الـ transcript والـ model وtool.done جميعًا null.
ما يجب أن تعرفه:
  • النتيجة وحدها تُخزَّن. لا تُرسل الـ snapshots إلى الـ model، ولا تُضاف إلى الـ transcript ولا الـ session، ولا يُحفظ لها checkpoint ولا تُسجَّل في trace spans. ترى الـ hooks (postToolCall، onToolResult) النتيجة فقط.
  • الـ crash يضيّعها. المخرجات الجزئية ليست durable: بعد crash لا تكون للـ call نتيجة بعد، فيعمل من البداية من جديد (tool.start جديد، وindex من 0). والتوقف لـتسجيل دخول داخل الـ generator يعيده من البداية أيضًا، لكن الـ run المستأنف يبلّغ tool.resume وليس tool.start ثانيًا، وindex من 0 كذلك. تبقى الـ snapshots التي بُثّت في سجل الأحداث؛ ويجب على الـ UI أن تتخلص منها عندما يتوقف الـ call أو يبدأ من جديد (روابط الـ UI تفعل ذلك).
  • الـ approvals والصلاحيات أولًا. الـ generator tool الذي يحتاج approval يعمل، ويبث، فقط بعد القرار (وكذلك عند resume مبثوث، agent.approvals.streamResolve()).
  • الإلغاء. عندما يُلغى الـ run، يتوقف الـ SDK عن قراءة الـ generator فورًا، ويختم الـ call كملغى ويستدعي return() الخاصة به، فتعمل كتل finally — بعد أن ينتهي الـ await الذي يقف عنده، لذلك مرّر ctx.abortSignal إلى العمل الذي تنتظره.
  • تُحجب الـ tokens في الـ snapshots أيضًا. الـ snapshot الذي يحتوي token أخذه الـ tool من ctx.getToken() يُستبدل بـ [REDACTED]، كما في النتيجة. الـ hook postToolCall الذي يعيد كتابة النتيجة لا يرى الـ snapshots: إذا كانت مخرجات tool يجب أن تُفلتَر بـ hook، فافلترها داخل الـ tool أو لا تبثّها.
  • أي القيم تُبث. فقط القيمة التي تملك next() وهي أيضًا async iterable (ما تُرجعه async function*) هي التي تُبث. أما النتيجة التي هي async iterable فقط، مثل ReadableStream، فهي نتيجة عادية.
  • الـ run كله محسوب. يحجز toolConcurrency الـ slot حتى ينتهي الـ generator. إذا استدعيت execute الخاصة بالـ tool بنفسك فسيُرجع لك الـ generator.
  • أين. الحلقة الرئيسية، والـ call الذي يعمل بعد approval، وnode استدعاء الـ tool في الـ flow (التي تحتفظ بالنتيجة فقط) كلها تمر على الـ generator؛ أما sandboxExecute الخاصة بالـ tool فلا تبث. في AI SDK UI stream، الـ snapshots هي مخرجات tool أولية (انظر AI SDK UI).