الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.
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.
الدالة نفسها موجودة في الـ API الكامل: 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 نفسه.
كل event فيه 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

عندما ينفّذ الـ provider stream() (كل الـ 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'.
لإضافة input إلى run ما زال يعمل، أو لإعادة توجيهه، راجع الـ queued input والـ steering: 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).
في المتصفح:
لواجهة chat بـ React فوق endpoint من هذا النوع، راجع React: 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: