agent.stream()؛ راجع Streaming.
Queued input
run.enqueue(input) تضيف input من المستخدم (string، أو content parts، أو Message[]) إلى run ما زال يعمل — مثل متابعة يكتبها المستخدم بينما الـ agent يعمل. الـ run لا يتوقف: ينضم الـ input إلى الـ transcript في أول نقطة آمنة — بعد نتائج tools الخطوة الحالية، ولا يدخل أبدًا بين turn فيها tool calls ونتائجها — والـ model call التالية تراه كأن المستخدم كتبه بنفسه. والـ input الذي يُضاف إلى الـ queue بينما الـ model يكتب رده الأخير يأخذ خطوة إضافية، فيرد عليه الـ model في الـ run نفسه. بادئة vendor/ في اسم الـ model تحدد الـ provider؛ ومع OpenRouter استخدم openrouter/<vendor>/<model> (مثل openrouter/openai/gpt-4o-mini).
enqueue() تُرجع { id, applied }. يظهر الـ id في حدثي input.queued وinput.applied. وتكون applied بقيمة false إذا كان الـ run قد انتهى أصلًا: لم يُؤخذ الـ input، فأرسله بنفسك كـ turn جديد (session.send()). وإلا فهي promise تُحل إلى true حالما يدخل الـ input الـ transcript، أو إلى false إذا توقف الـ run قبل الـ model call التالية (أُلغي، أو توقف عند approval (موافقة)، أو نفدت maxSteps أو الـ budget، أو فشل)؛ وحينها يبقى الـ input أيضًا من مسؤوليتك.
- عدة inputs تُضاف إلى الـ queue قبل الـ model call نفسها تُطبَّق معًا، بترتيب إضافتها.
- مع checkpointing (
sessionIdأو durable session)، يُحفظ الـ input الذي ما زال ينتظر فورًا في آخر checkpoint للـ run — في الخانة نفسها التي يُحفظ فيها الـ input المنتظر خلف tool calls بلا نتيجة (راجع Durable execution). إذا حدث crash أو فشل الـ run، فلا يضيع الـ input:agent.resume()تطبّقه (لكنappliedالخاصة بـ run فشل داخل الـ process تبقى تُحل إلىfalse). أما الـ run الذي انتهى أو توقف أو أُلغي فلا يحتفظ به. - بدون stream: مرّر
InputQueueكـExecuteOptions.inputQueueواستدعِpush()عليه — وهو الـ queue نفسه الذي يقف خلفrun.enqueue(). كل queue يخدم run واحدًا. - في الـ session، تجعل
agent.session({ turnPolicy: 'queue' })أيsend()أوstream()تُستدعى أثناء turn جارية (أو تنتظر البدء) تنضم إلى الـ turn نفسها بالطريقة نفسها. راجع Sessions.
متقدم: executor API
بدون stream: مرّرInputQueue إلى AgentExecutor.execute() (راجع executor API):
Steering
run.steer(input) تحوّل run جاريًا إلى input جديد من المستخدم — مثلما يحدث عندما يغيّر المستخدم رأيه والـ agent ما زال يفكّر:
- إذا كانت هناك model call جارية لم تُخرج بعد نصًا ولا tool calls: تُلغى بإشارة abort خاصة بها، لا بإشارة الـ run، فيستمر الـ run. يُهمل ناتجها الجزئي، ويُضاف
inputكرسالة user، ويُستدعى الـ model من جديد. تكونappliedبقيمة'immediate'، وتنتهي خطوة الـ call الملغاة بـstep.done'steered'. والـ provider الذي يتجاهل إشارة الـ abort لا ننتظره؛ ويُهمل رده المتأخر. - إذا كان الـ model قد أخرج نصًا أصلًا (أو tool calls)، فإن الـ
inputينتظر النقطة الآمنة التالية مثلenqueue(): وتكونappliedبقيمة'queued'. - الـ tool calls الجارية تكتمل وتُحفظ نتائجها؛ أما التي لم تبدأ من الـ turn نفسها فلا تعمل وتأخذ النتيجة المعتادة “cancelled before it ran”. بعد ذلك يُطبَّق الـ input.
- تصبح
appliedبقيمةfalseبعد انتهاء الـ run: أرسل الـ input كـ turn جديد.
steer() تُرجع { id, applied, joined }: يظهر الـ id في input.steered وinput.applied، وjoined promise تبيّن هل وصل الـ input إلى الـ transcript أم لا (مثل applied في enqueue()). الـ call الملغاة تُحسب خطوة من maxSteps. ومع checkpointing، يُحفظ الـ input في آخر checkpoint حالما يُؤخذ وقبل أن يُستدعى الـ model من جديد — فإذا حدث crash أثناء التحويل فلا يضيع؛ أما الـ turn الجزئية المُهملة فلا تُحفظ في أي checkpoint أبدًا. وبدون stream، استدعِ steer() على ExecuteOptions.inputQueue الخاص بالـ run. وفي الـ session، تجعل agent.session({ turnPolicy: 'steer' }) أي send() أو stream() تُستدعى أثناء turn جارية توجّه تلك الـ turn (راجع Sessions).