agent.stream() تشغّل الـ agent بطريقة agent.send() نفسها بالضبط، وتُرجع لك
الـ run كـ stream من أحداث typed: نص الـ model حالما يصل، وكل tool call،
وحدود الخطوات، وطلبات الـ approval (الموافقة)، وفي النهاية run.done. كل event
كائن JSON عادي، فيمكنك تمريره إلى المتصفح عبر Server-Sent Events أو WebSocket
دون أي تحويل. بادئة vendor/ في اسم الـ model هي التي تختار الـ provider؛
ومع OpenRouter استخدم openrouter/<vendor>/<model> (مثال
openrouter/openai/gpt-4o-mini).
المقتطفات في هذه الصفحة تترك لك بعض الأسماء:providerهو أيLLMProvider(بدون اتصال:createMockProvider())؛ وagentهو ناتجcreateAgent()؛ وinputهو نص المستخدم، من نوعstring؛ وapprovalStoreهوApprovalStore؛ وtoolRegistryهوToolRegistry.
AgentExecutor.stream(options) تأخذ
خيارات AgentExecutor.execute() نفسها (الـ approval store، والـ checkpoints،
والـ hooks، والـ tracing، وtoolConcurrency، …).
هذه الأحداث، أي الـ union AgentEvent، هي نظام الأحداث الوحيد في الـ SDK:
الـ stream، وخيارات الـ listener، وsession.on()،
والـ UI hooks، وroutes السيرفر، وACP والقنوات — كلها تنقل الأحداث نفسها.
الـ AgentRun
stream() تُرجع AgentRun:
- الـ run يبدأ فورًا. لا تحتاج إلى إجراء iterate عليه:
await run.resultوحده يوصل الـ run إلى نهايته. resultيعود بـExecutionResultنفسها التي تُرجعهاsend()، ويرفض بالخطأ نفسه الذي كانتsend()سترفضه. الـ run الملغى يُرجعfinishReason: 'aborted'؛ والـ run الموقوف بانتظار approval يُرجعfinishReason: 'awaiting-approval'معapprovalId. تركresultدونawaitلن يسبّب أبدًا unhandled rejection.- الـ run الفاشل يرمي الخطأ من الحلقة. عندما يفشل الـ run، تُخرج
for awaitحدثَيerrorوrun.done { finishReason: 'error' }، ثم ترمي من جديد الخطأ الذي يرفض بهrun.result(الخطأ نفسه الذي كانتsend()سترميه)، فـtryحول الحلقة يلتقطه. مرّر{ throwOnError: false }إلىstream()لتنتهي الحلقة بشكل عادي وتقرأ الفشل من الأحداث أو منrun.result. الإلغاء، والخروج المبكر بـbreak، والتوقف بانتظار approval لا ترمي خطأ أبدًا. أما streams الـ session وapprovals.streamResolve()فما زالت تنتهي بشكل عادي. - إذا خرجت من حلقة
for awaitمبكرًا، يُلغى الـ run (عبر مسارsignalنفسه، راجع الإلغاء). وعندهاresultيُرجعfinishReason: 'aborted'. - لا backpressure ولا يضيع شيء. الـ run لا ينتظر المستهلك أبدًا. تتراكم الأحداث في buffer حتى تقرأها، فيرى المستهلك البطيء كل حدث وبالترتيب. وحتى لو أجريت iterate بعد نهاية الـ run، تصلك أحداثه كلها.
enqueue(input)تضيف input من المستخدم إلى الـ run أثناء عمله: يدخل سجل المحادثة قبل الـ model call التالي. راجع الـ input المنتظر.steer(input)تعيد توجيه الـ run: الـ model call التي لم تُنتج شيئًا بعد تُلغى وتتكرر مع الـ input الجديد. راجع الـ steering.- مستهلك واحد. لا يمكنك إجراء iterate على
AgentRunإلا مرة واحدة؛ وfor awaitثانية ترمي خطأ. لتوزيع الأحداث على أكثر من جهة، اجمعها بنفسك. - الخيارات غير الصالحة — غياب
providerأوagentأوinput، أوtoolConcurrencyخاطئ — تجعلstream()يرمي الخطأ بشكل متزامن.
الاستماع بدون iterating
الـ listener الذي يرمي خطأ لا يُفشل الـ run (فقد تكون أدواته أحدثت آثارًا جانبية بالفعل): الخطأ يُسجَّل مرة واحدة لكل run عبرconsole.warn ويكمل الـ run.
لمراقبة كل run دون إجراء iterate على stream، أعطِ الـ agent listener:
createAgent({ onEvent })، أو onAgentEvent في خيارات
AgentExecutor.execute() / stream() / resumeAfterApproval(). يصل إلى الـ listener
كل AgentEvent لحظة حدوثه وبشكل متزامن، في send() كما في stream()،
وفي turns الـ session وفي الـ runs التي تُستأنف بعد approval. وتصله الأحداث نفسها
وبالترتيب نفسه الذي كنت ستراه لو أجريت iterate على الـ stream: مع وجود
listener، حتى send() وexecute() تُجري stream لكل model call، فيصلك نص الخطوة
على عدة أحداث text.delta (إذا كان الـ provider لا يستطيع إجراء stream، يصل
text.delta واحد لكل خطوة). اجمعها معًا، أو استخدم text.done للنص
الكامل لكل خطوة؛ وAgentExecutor.execute({ streamModelCalls: false }) تولّد
خطوات كاملة. الـ output guardrails تفحص فقط الرد النهائي لـ send()، كما هو
الحال بدون listener. وأحداث الـ sub-agents تصل موسومة بـ subagent.
الانتقال من onEvent / ExecutionEvent
ExecuteOptions.onEvent ونوعه ExecutionEvent حُذفا في هذا الإصدار (كانا
deprecated منذ إصدار سابق). مرّر بدلها onAgentEvent إلى
AgentExecutor.execute() / stream() / resumeAfterApproval() — أما
createAgent({ onEvent }) فتستقبل أحداث AgentEvent أصلًا ولم تتغير.
الجدول أدناه يربط أسماء الأحداث القديمة بأحداث AgentEvent التي يستقبلها الـ
listener الآن:
AgentEvent يبلغك أيضًا عن أشياء لم يكن ExecutionEvent يوصلها أبدًا: حدود
الخطوات، طلبات الـ approval، قرارات الصلاحيات، الـ budgets، الـ guardrails،
الـ input المنتظر والموجَّه (queued وsteered)، الـ compaction، الـ reasoning،
retries الـ provider، الـ agent drift، والـ handoffs (راجع
الـ schema).
الـ streaming لـ turn في session
session.stream(input, { signal }) تعمل stream لـ turn واحد من
session (جلسة) متعددة الـ turns وتُرجع AgentRun نفسه. يرى الـ run
المحادثة حتى تلك اللحظة، وعندما ينتهي يُحفظ الـ turn في store الـ session،
تمامًا كما تحفظه session.send(). وrun.done يصل بعد الحفظ، فيكون سجل
المحادثة كاملًا عندما تنتهي الحلقة. أما الـ run الملغى أو الفاشل، أو الذي توقفت
عن قراءته مبكرًا، فلا يُحفظ.
الـ streaming بعد الـ approval
الـ run الذي توقف بانتظار approval يستطيع أن يكمل كـ stream أيضًا.agent.approvals.streamResolve() (أو streamAnswer()) تُرجع
AgentRun يكون الـ result فيه هو نفسه ما تُرجعه agent.approvals.resolve().
أحداثه: run.start، ثم tool.resume وtool.done للـ call التي حُسم أمرها
(tool.error في حالة الرفض — tool.resume وليس tool.start ثانية، لأن الـ
run الموقوف كان قد أبلغ عن بداية تلك الـ call)، ثم أحداث الاستكمال نفسها كما
في run جديد، حتى run.done. وإذا حدث توقف آخر، ينتهي الـ stream بـ
approval.requested (مع kind: 'sign-in' ورابط signIn عندما تنتظر أداة
تسجيل دخول OAuth). الإلغاء وenqueue()
وsteer() تعمل بالطريقة نفسها، والـ approval يمكن أن تأتي من process أخرى،
لأن كل شيء يُقرأ من الـ approval store. وإذا كان الـ model يُختار لكل run
(model دالة)، فالمستخدم هو نفسه الذي استخدمه الـ run الموقوف.
متقدّم: executor API
مع الـ executor مباشرة،streamResumeAfterApproval() تأخذ وسائط
resumeAfterApproval() نفسها (راجع الـ executor API)
وتُرجع AgentRun نفسه.
type وrunId وseq وtimestamp وv. القائمة الكاملة لأنواع
الأحداث وضمانات الترتيب ومساعدات TypeScript وقواعد الإصدارات موجودة في
Stream events.
Sub-agents
عندما يفوّض الـ agent العمل عن طريق أداةtask
(راجع Sub-agents)، يصل run الـ sub-agent داخل الـ
stream نفسه: خطواته وأحداث text.delta وtext.done وأحداث الـ tool والأخطاء تظهر
بين tool.start وtool.done (أو tool.error) للـ lead في تلك الـ call،
وكلها تحمل حقل subagent:
toolCallId هو الـ tool call لدى الـ lead الذي بدأ الـ sub-agent؛ والـ
sub-agent التابع لـ sub-agent آخر يحمل depth: 2 والذي يحتويه في parent.
الأحداث التي لا تحتوي subagent تخص الـ run في المستوى الأعلى: ضمانات الترتيب
المذكورة أعلاه تسري عليها، وتسري بشكل مستقل على خطوات كل sub-agent (وعدة
sub-agents يعملون بالتوازي تتداخل أحداثهم). run.start وrun.done يخصّان
الـ run في المستوى الأعلى فقط، فيظهران مرة واحدة بالضبط. والـ sub-agent الذي
يتوقف بانتظار approval يُبلَغ عنه مرة واحدة، عبر approval.requested في
المستوى الأعلى (وهي تحمل الـ call الخاصة بالـ sub-agent).
Token streaming والـ providers
عندما ينفّذ الـ providerstream() (كل الـ providers المدمجة تنفذها،
وmockModel كذلك)، تخرج كل خطوة model كـ stream وتصل أحداث text.delta مع
إنتاج الـ model للنص. والـ tool calls تتجمّع من الـ stream. وإذا لم يكن لدى الـ provider
stream()، أو كانت supportsStreaming(model) تُرجع false، تعود الخطوة
إلى generate() ويصل نصها في text.delta واحد يتبعه text.done.
الـ streaming يغيّر فقط طريقة الحصول على خطوة model واحدة. الـ hooks،
والتحقق من الـ arguments، والـ approvals، والـ tool calls المتوازية، والـ
checkpoints، والإلغاء، والـ tracing spans، وباقي callbacks في execute() —
كلها تتصرف تمامًا كما في send(). وsend() وexecute() تُجري stream بالطريقة
نفسها عندما يكون لديها listener (onEvent / onAgentEvent)؛ وبدونه
تستخدم generate().
يجب أن تُخرج stream() في الـ provider المخصص chunks من نوع text-delta
وchunk أخيرًا finish فيه finishReason وusage. يمكنك إخراج الـ tool calls
كـ chunks من نوع tool-call، أو تُنجزها على الـ promise toolCalls في
StreamResult. وchunk من نوع error يفشّل الخطوة.
الإلغاء
مرّرsignal لإيقاف run من الخارج، أو اخرج من الحلقة. كلاهما ينهي الـ run
بطريقة send() الملغاة نفسها: يُفحص الـ signal بين chunks الـ stream، وقبل كل
model call وكل tool call، ويصل إلى الـ provider والـ tools. ينتهي الـ stream بـ
step.done ('aborted' إذا كانت هناك خطوة تعمل) ثم run.done
('aborted')، وresult يُرجع finishReason: 'aborted'.
run.enqueue(input) تنتظر النقطة
الآمنة التالية، وrun.steer(input) تقاطع الـ model call الحالي.
مثال: terminal
مثال: Server-Sent Events
كل event serializable كـ JSON، فنقطة نهاية SSE ليست إلاres.write واحدًا
لكل event. ألغِ الـ run عندما ينقطع اتصال العميل. أما مع turns الـ session، فإن
createRouteHandler() يفعل العكس افتراضيًا: يكتمل الـ turn ويُحفظ حتى لو
غادر العميل (راجع Next.js).
useLoushoAgent() يرسل الـ input بـ POST ويقرأ أسطر data: نفسها.
lousho dev يقدّم الصيغة نفسها بـ session لكل تبويب في المتصفح: POST /chat
مع { sessionId, input } يُجري stream لـ agent.session({ id }).stream(input)
كأسطر data: تنتهي بـ event: done، والـ approvals تُحسم عبر
POST /chat/:sessionId/approvals/:id (راجع CLI).
متقدّم: executor API
AgentExecutor.stream() تقبل كل خيارات execute() (راجع
الـ executor API). هنا tool يحتاج approval ينهي الـ
stream بـ approval.requested: