أسباب الانتهاء
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(يُرسل إلىaiSDK باسم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 ثانية عن دورة سبق حفظها.