الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.

أسباب الانتهاء

result.finishReason تقول لك لماذا انتهى الـrun. يمكن أن يكون سبب الـmodel نفسه لدورته الأخيرة: 'stop' أو 'length' أو 'tool_calls' أو 'content_filter' أو 'error' أو 'other'، وأي سبب يبلّغ عنه الـprovider خارج هذه القائمة يصبح 'other'. أو 'awaiting-approval' إذا توقف الـrun على tool call تحتاج approval من إنسان. أو 'aborted' إذا ألغيته بـsignal. أو 'max-steps'. أو 'output-invalid' إذا لم يطابق الرد output schema حتى بعد خطوة الإصلاح — راجع Structured output. أو 'budget-exceeded' إذا ضربت ميزانية في limits مثل maxTokens أو maxCostUsd، وresult.budget تحدد أيّ واحدة — راجع الميزانيات. أو 'guardrail' إذا حجب guardrail إدخال أو إخراج أو أدوات الـrun، وresult.guardrail تحدد أيّ واحد — راجع guardrails الإدخال والإخراج. النوع (ExecutionFinishReason) هو union مغلق، فالمقارنة بسبب مكتوب بشكل خاطئ لا تمر في الـcompile. 'max-steps' تعني أن ميزانية maxSteps (الافتراضية 10) انتهت والـmodel ما زال يريد أن يكمل، فقد يكون الرد فارغًا أو جزئيًا. الـrun الذي ينتهي طبيعيًا ضمن الميزانية يحتفظ بـ'stop'. الخطوات التي تأتي من initialSteps أو من استئناف بعد approval تُحسب ضمن الميزانية، وresult.steps هو عدد الخطوات التي تمت. السبب نفسه موجود في run.done ضمن streaming، وفي finish الذي هو مقابلها في onEvent الـdeprecated.

الإلغاء

مرّر AbortSignal لإيقاف الـrun: agent.send(input, { signal })، أو AgentExecutor.execute({ ..., signal })، أو resumeAfterApproval(..., { signal }).
لمهلة زمنية استخدم AbortSignal.timeout(ms):
كيف يتصرف الإلغاء:
  • الـsignal يُفحص قبل كل call للـmodel وقبل كل tool call. ويُمرَّر إلى الـprovider عبر GenerateOptions.signal (يُرسل إلى ai SDK باسم abortSignal) وإلى كل tool عبر execute(args, { abortSignal })، فيستطيع العمل الجاري أن يتوقف مبكرًا. الـhttpTool الجاهزة تمرره إلى fetch، والـruns الفرعية المفوَّضة (أداة task) تُلغى مع الـrun الأب.
  • الـrun الملغى يُرجع نتيجة ولا يرمي rejection: finishReason: 'aborted' مع الرسائل والخطوات التي تمت. إذا قطع الإلغاء call للـmodel يعمل بالـstreaming، يبقى النص الذي بثّه في result.text (وفي رسالة assistant معلَّمة بـinterrupted). الـrejection الناتج عن الإلغاء، مثل AbortError، لا يُعتبر فشلًا: أغلفة الـretry والـfallback الخاصة بالـprovider لا تعيد محاولته، ولا يُختصر إلى خطأ provider.
  • أحداث الـrun تنتهي بـrun.done مع finishReason: 'aborted'.
  • الـrun لا ينتظر provider يتجاهل الـsignal: يُترك الـcall للـmodel لحظة الإلغاء (ويُهمَل رده المتأخر وأي شيء يبثّه بعدها) وينتهي الـrun بـ'aborted'. ولا يُنتظر كذلك الـtool الذي يتجاهل abortSignal الخاص به: ينتهي الـrun بـ'aborted' دون call جديد للـmodel، ويأخذ الـcall الذي ما زال يعمل نتيجة ‘cancelled’، ويستمر الـtool في العمل في الخلفية (والنتيجة التي تصل في لحظة إطلاق الـsignal نفسها تُحفظ). defineTool({ timeoutMs }) يضع حدًا لمدة call الـtool: الـcall الذي ما زال يعمل عندها يفشل بخطأ tool يراه الـmodel، والـrun الذي يُلغى أثناء تشغيل call كهذا يتوقف عن انتظاره.
  • result.abortReason يقول لك السبب: سبب الـsignal على شكل { name, message }، حيث name هو 'TimeoutError' مع AbortSignal.timeout()، و'AbortError' مع controller.abort() (مع نص السبب إذا كان string، مثل controller.abort('user left'))، أو اسم الـError نفسه إذا كان السبب Error.
  • مع sessionId وcheckpointStore تُحفظ الحالة في checkpoint. إذا استدعيت execute() ثانية بنفس الـsessionId يكمل الـrun من حيث توقف، وأي input جديد ينضاف كرسالة مستخدم تالية (راجع Durable execution). الـtool calls التي لم يصلها الـrun تأخذ نتيجة { error } تفيد بأنها أُلغيت، فتبقى المحادثة صالحة للـprovider.
  • الـsignal الملغاة مسبقًا ترجع فورًا دون استدعاء الـprovider.

Tool calls متوازية

عندما يطلب الـmodel عدة tools في دورة واحدة تعمل بالتوازي. toolConcurrency (في createAgent() وAgentExecutor.execute()) تحدد أكبر عدد يعمل في نفس الوقت: عدد صحيح موجب، أو 'unbounded' (الافتراضي). استخدم 1 لتنفيذ متسلسل صارم، مثلًا عندما تتشارك الـtools حالة لا يُؤمَن لمسها بالتوازي.
الضمانات، أيًّا كان الحد:
  • ترتيب السجل هو ترتيب الاستدعاء. تُضاف نتائج الـtools بالترتيب الذي طلب به الـmodel الـcalls، لا بترتيب انتهائها، فيكون طلب الـprovider التالي deterministic.
  • الأحداث. الـcalls تبدأ بترتيب الطلب. حدث tool.start للـcall وonToolCall وvalidation الوسائط وhooks الـpreToolCall وفحص needsApproval تعمل قبل بدايتها مباشرة، call واحدة كل مرة. حدث tool.done (أو tool.error) يُطلق عند انتهائها، فالنتائج تصل بترتيب الانتهاء. مع toolConcurrency: 1 تتعاقب أحداث البدء والتسوية تمامًا كما كانت.
  • الموافقات. أول call تحتاج approval توقف الدفعة: الـcalls التي قبلها تعمل (بالتوازي) وتُسجَّل نتائجها، ثم يتوقف الـrun على هذه الـcall (finishReason: 'awaiting-approval'). الـcalls التي بعدها لا تبدأ في هذا الـrun. resumeAfterApproval() تسجّل نتيجة الـcall المتوقفة (أو رفضها) ثم تشغّل الـcalls اللاحقة بنفس الطريقة، فكل call في الدورة تحصل على نتيجة واحدة بالضبط — راجع Durable execution.
  • الإخفاقات معزولة. الـtool التي ترمي خطأ تأخذ نتيجة خطأ خاصة بها، وأخواتها تكمل. الخطأ المنتشر (PropagatingToolError، مثل حاجز عمق التفويض أو hook يرمي) يمنع بدء calls جديدة، وينتظر الجارية حتى تستقر، ثم يرفض الـrun. لا تبقى أي tool تعمل منفصلة.
  • الإلغاء. إلغاء أثناء تشغيل دفعة ينهي الـrun بـfinishReason: 'aborted'. الـcalls التي انتهت تحتفظ بنتائجها، والباقي تأخذ نتيجة تفيد بأنها أُلغيت. الـtools الجارية ترى الإلغاء عبر abortSignal الخاص بها.
  • Checkpoints. مع sessionId وcheckpointStore تُحفظ دورة الـmodel في checkpoint قبل أن تبدأ أي call، ثم تُحفظ من جديد كلما زاد طول سلسلة الـcalls المنتهية بالترتيب (ومع 1، بعد كل call). الـrun المستأنف لا يعيد تشغيل call مسجَّلة، ولا يسأل الـmodel ثانية عن دورة سبق حفظها.