defineTool(): تُستنتج أنواع الوسائط والنتيجة من zod input، وتمر الوسائط على validation قبل أن تعمل execute، ويمكن وضع النتيجة في أي مكان يقبل tools (createAgent({ tools: [...] })، ToolRegistry.register(tool)، AgentBuilder.addTool(tool)).
تترك الأمثلة في هذه الصفحة بعض الأسماء لك:providerهو أيLLMProvider(بدون إنترنت:createMockProvider()).
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()).
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.
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]، كما في النتيجة. الـ hookpostToolCallالذي يعيد كتابة النتيجة لا يرى الـ 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).