الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.
الـflow هو سير عمل ثابت من عدة خطوات، يشغّله agent واحد. تكتب الخطوات وترتيبها مسبقاً، بدلًا من أن تترك القرار للـmodel. صف الـgraph بـFlowBuilder، وشغّله بالدالة static FlowExecutor.execute(flow, context, onEvent?).
الـmodel الذي تستخدمه خطوة llmCall هو الـmodel الخاص بها، وإلا فـsettings.model الخاص بالـagent، وإلا فالـmodel الافتراضي للـprovider (gpt-4o-mini في المثال أعلاه). كلا الإعدادين هو معرّف الـmodel المجرّد لدى الـprovider، مثل 'gpt-4o'، ويُمرَّر إلى provider.generate() كما هو: ليس spec بصيغة 'openai/gpt-4o'، فهذه الصيغة يقرؤها فقط resolveProvider() وcreateAgent({ model }). خطوة llmCall ترجّع نص الرد، وليس لها خيار structured output (schema). إذا أردت نتيجة typed، حلّل النص في خطوة لاحقة، أو استدعِ كـtool agentاً له structured output (راجع تشغيل agent داخل flow).

قيم القوالب

الـplaceholder بصيغة {{name}} داخل prompt، أو رسالة throw، أو argument لـtool، يُستبدل بنص المتغير:
  • الـstring يُستخدم كما هو؛ والرقم أو الـboolean يصبح نصه (0 يصبح '0')؛ والمتغير غير المضبوط، أو الذي قيمته null، يصبح ''.
  • الكائن الذي حقله الوحيد text (نتيجة MCP tool، أي { text }) يصبح ذلك النص، وكذلك نتيجة MCP الخام ({ content: [{ type: 'text', text }] }، وتُجمع أجزاؤها النصية مفصولة بأسطر جديدة).
  • أي كائن أو مصفوفة أخرى تصبح JSON الخاص بها، فنتيجة toolCall المخزّنة في outputVariable تظهر في الـprompt التالي كـ{"city":"Oslo","temp":4}، لا كـ[object Object].
  • المسار المنقّط يقرأ داخل كائن أو مصفوفة: {{weather.city}}، {{results.0.title}}. تُقرأ الخصائص الخاصة بالكائن نفسه فقط ({{res.constructor}} تعطي '')، وأي جزء مفقود في المسار يعطي ''.
خطوة evaluator تخزّن نتيجتها في outputVariable أيضاً، مثل llmCall وtoolCall.

أنواع العُقد

FlowExecutor يشغّل أنواع العُقد هذه: شروط oneOf وتعبيرات evaluator تمر على لغة تعبيرات صغيرة وآمنة: لا eval ولا كود host. اللغة تربط الـ{{name}} placeholders كقيم، ولا تلصقها في نص التعبير. قواعدها النحوية وقواعد فشلها في تعبيرات الـflow.

استدعاءات الـtool

خطوة toolCall تمر بنفس الفحوصات التي يمر بها استدعاء tool في run للـagent قبل أن تعمل الـtool:
  • الـarguments، بعد تعويض الـ{{variable}}، تُتحقَّق مقابل الـinput schema الخاص بالـtool. الـarguments التي لا تطابق تفشّل الخطوة بـLOUSHO_TOOL_ARGS_INVALID، مع قائمة بكل مشكلة، ولا تُستدعى الـtool.
  • الـpermissions وpermissionMode وonPermissionDecision في context الـflow تنطبق كما تنطبق في createAgent() (راجع سياسات الصلاحيات وأوضاع الصلاحيات).
  • الاستدعاء الذي يحتاج approval (عبر needsApproval الخاص بالـtool، أو قاعدة ask) يحسمه الـcallback approve في الـcontext، وله نفس شكل createAgent({ approve }). القيمة true (أو ملاحظة) تشغّل الـtool. وfalse ترفضها بـLOUSHO_FLOW_TOOL_DENIED. وعندما يُرجع approve القيمة 'defer'، أو لا يوجد callback approve أصلاً، يتوقف الـrun المتين حتى يقرر شخص ما (راجع الإيقاف بانتظار الموافقة). أما الـrun غير المتين فيرفض الاستدعاء بـLOUSHO_FLOW_TOOL_DENIED. الـtool لا تعمل أبداً دون approval.

قيم الـarguments

الـargument الذي يكون string عبارة عن placeholder واحد بالضبط، '{{name}}' أو '$name'، يمرّر قيمة المتغير كما هي: الرقم يبقى رقماً، والكائن يبقى كائناً؛ و'{{res.count}}' يمرّر قيمة ذلك الحقل. فـarguments: { n: '{{n}}' } مع n = 5 يمرّر 5 إلى tool الـschema الخاص بها z.number(). وهذا ينطبق أيضاً داخل المصفوفات والكائنات المتداخلة. أي string آخر يُعوَّض كنص: 'n is {{n}}' يصبح 'n is 5'. والـplaceholder لمتغير غير مضبوط يبقى كما كان سابقاً: '{{missing}}' يصبح ''، و'$USD' (لا يوجد متغير اسمه USD) يبقى الـstring الحرفي '$USD'.
الـinputs المعلنة للـflow تُفحص قبل أن تعمل الخطوة الأولى. الـinput المطلوب (required) المفقود، أو القيمة ذات النوع الخاطئ، يفشّل الـflow بـLOUSHO_VALIDATION_FAILED.

إلغاء الـflow

مرّر signal في الـcontext لتلغي الـrun. يُفحص قبل كل خطوة: بمجرد أن يُلغى (aborted)، لا تبدأ أي خطوة أخرى ويفشل الـflow بالـreason الخاص بالـsignal. والخطوة الجارية تستلم الـsignal أيضاً: llmCall يمرّره إلى طلب الـmodel، وtoolCall يسلّمه للـtool كـctx.abortSignal.
عندما يفشل فرع في خطوة parallel، تُلغى الفروع الشقيقة بالطريقة نفسها: لا تبدأ أي خطوة أخرى، وllmCall أو toolCall الجاري فيها يستلم signal ملغى. الـflow يُرجع خطأ الفرع الأول فقط بعد أن تستقر كل الفروع، فلا تعمل أي tool ولا يُضاف أي event إلى result.events بعد إرجاع النتيجة. الـtool التي تتجاهل ctx.abortSignal تكمل حتى النهاية، والـflow ينتظرها. result.usage يجمع استهلاك الـmodel (promptTokens، completionTokens، totalTokens، وcachedInputTokens، reasoningTokens، costUsd عندما تُبلَّغ) لكل llmCall في الـrun، بما فيها الفاشلة. الخطوة التي ليس لها id تأخذ واحداً فريداً داخل الـrun (step-1، step-2، … بترتيب بدء الخطوات)، لتتمكن من مطابقة events الـstep-start والـstep-complete عبر stepId.

إعادة المحاولة وحدود الوقت

أي عقدة يمكن أن يكون لها retry وtimeoutMs. هذا يشمل llmCall وtoolCall وsequence وparallel وforEach.
  • retry: { maxAttempts, backoffMs? } يعيد تشغيل العقدة الفاشلة، حتى maxAttempts محاولة إجمالاً. ينتظر backoffMs * 2^(attempt - 1) ms قبل كل إعادة (الافتراضي 0). كل محاولة فاشلة تُعاد تُطلق event step-retry فيه { attempt, maxAttempts, delayMs } والـerror الخاص بالمحاولة. فقط الفشل الأخير يُطلق step-error. الـrun الملغى (signal) لا يُعاد، ولا يُعاد فشل الـmodel الذي لا تصلحه إعادة المحاولة (راجع أدناه).
  • timeoutMs يفشّل المحاولة التي تتجاوز المدة بـLOUSHO_OPERATION_TIMEOUT (وهو TimeoutError). طلب الـmodel أو استدعاء الـtool في تلك المحاولة يستلم signal ملغى. والمحاولة التي انتهت مهلتها تُعاد مثل أي فشل آخر. الـtool التي تتجاهل ctx.abortSignal تستمر في العمل في الخلفية.
خطوة llmCall التي يفشل طلب الـmodel فيها تفشل بنفس CompactedLLMProviderError الذي يُرفض به run الـagent، لا بالخطأ الخام من الـSDK الخاص بالـprovider: الـcode هو LOUSHO_PROVIDER_RATE_LIMITED عند 429 وLOUSHO_PROVIDER_REQUEST_FAILED في غير ذلك، وcompacted يحمل { error, category, retryable, statusCode?, providerName? }. الفشل الذي فيه retryable: false (مثل 'auth-failure' كـ401 أو API key غير صالح، أو 'quota-exceeded'، أو 'context-length-exceeded') يفشّل الخطوة فوراً، دون استهلاك محاولات retry المتبقية؛ أما الـrate limit أو الـtimeout أو أخطاء 5xx فتُعاد. القيم غير الصالحة (maxAttempts أقل من 1 أو ليس عدداً صحيحاً، أو backoffMs سالب، أو timeoutMs <= 0) تفشّل الخطوة بـLOUSHO_FLOW_INVALID.
الـcontainer الذي يُعاد يشغّل أبناءه من جديد. الاستثناء هو الـrun المتين (أدناه): فيه تُتخطّى الأبناء التي اكتملت في محاولة سابقة.

الـruns المتينة

مرّر checkpointStore وrunId لتجعل الـrun متيناً (durable). متغيرات الـrun، والعُقد التي اكتملت (مع نتائجها)، والفرع الذي أخذه كل oneOf، والاستهلاك حتى الآن، تُحفظ تحت runId بعد كل عقدة تكتمل، ومرة أخرى لما ينتهي الـflow. والـrun الجديد يُحفظ أيضاً مرة واحدة قبل خطوته الأولى (بعد فحص الـinputs)، فحتى الـrun الذي تفشل خطوته الأولى يمكن استئنافه. أي CheckpointStore يعمل، مثل memoryStore().checkpoints أو store مبني على SQLite (راجع التنفيذ المتين). بعد crash، أو عندما تفشل خطوة، أكمل الـrun بـFlowExecutor.resume(flow, context). مرّر نفس checkpointStore وrunId. العُقد المكتملة لا تُشغَّل مرة أخرى: كل واحدة ترجّع نتيجتها المحفوظة، وoneOf يأخذ الفرع الذي أخذه سابقاً. كل ما عدا ذلك يعمل كالمعتاد، انطلاقاً من المتغيرات المحفوظة. result.usage وresult.steps يشملان المحاولات السابقة.
  • العقدة تُعرَّف بموقعها في الـflow، لا بالـid الخاص بها. استأنف الـrun بنفس الـflow الذي بدأه. الاستئناف بـflow له code مختلف يُرفض بـLOUSHO_CONFIG_INVALID. الـrun يحفظ أيضاً بنية الـflow (نوع كل عقدة، وid، والـtool أو الـagent، وترتيبها)؛ والاستئناف بنفس الـcode لكن مع خطوات أُضيفت أو حُذفت أو نُقلت يُرفض بـLOUSHO_FLOW_CHANGED، لأن النتائج المحفوظة ستقع على الخطوات الخطأ. تعديل prompt أو شرط أو أي إعداد آخر يبقي البنية كما هي. الـruns المحفوظة قبل هذا الفحص تُستأنف بدونه.
  • استئناف run منتهٍ يُرجع نتيجته المحفوظة بلا events، ولا يشغّل شيئاً. execute() مع runId لـrun منتهٍ يبدأ run جديداً. وexecute() مع runId لـrun لم ينتهِ يُرفض بـLOUSHO_CONFIG_INVALID؛ استأنفه بدلاً من ذلك، أو استخدم runId جديداً.
  • الـrun الذي ليس له checkpoint يُرفض بـLOUSHO_CHECKPOINT_NOT_FOUND. والـrun الذي كانت inputs المعلنة فيه غير صالحة لم يحفظ أي checkpoint: استدعِ execute() مرة أخرى بـinputs صالحة.
  • استدعاء واحد فقط يشغّل runId معيّناً في كل مرة. طوال عمل execute() أو resume()، يمسك run lease على الـrunId في الـstore، وهو نفس الـlease الذي يأخذه run الـagent (راجع التنفيذ المتين). أي execute() أو resume() آخر لنفس الـrunId يُرفض بـLOUSHO_SESSION_BUSY، ولا يشغّل شيئاً. هذا ينطبق في نفس الـprocess، وفي process أو replica أخرى على نفس الـstore، وعبر كائن store آخر فوق نفس البيانات. الـlease يتجدد أثناء عمل خطوة طويلة، ويُحرَّر لما يرجع الاستدعاء. إذا مات الـprocess الذي يمسكه، ينتهي الـlease (خلال 60 ثانية على الأكثر)، وعندها يمكن استئناف الـrun. الـCheckpointStore المخصص الذي ليس فيه acquireLease يعمل بدون leases.
  • العقدة المكتملة لا تُتخطّى إلا بعد حفظ الـcheckpoint الخاص بها، والـevent step-complete الخاص بها يُطلق بعد ذلك الحفظ، فالخطوة التي أُبلغ عن اكتمالها لا تُشغَّل مرة أخرى أبداً عند الاستئناف. أما العقدة التي انقطعت أثناء عملها (llmCall أو toolCall) فتعمل من جديد، لذلك اجعل الـtools ذات الآثار الجانبية idempotent.
  • المتغيرات ونتائج العُقد يجب أن تنجو من structuredClone، فلا دوال ولا instances لـclasses.
  • عنصر وفهرس دورة forEach لا يُحفظان. الدورة المنقطعة تعمل من جديد بعنصرها. والدورات المكتملة تُتخطّى.
result.status قيمته 'completed' أو 'failed' أو 'awaiting-approval' (راجع أدناه).

الإيقاف بانتظار الموافقة

في الـrun المتين، خطوة toolCall التي تحتاج approval توقف الـflow عندما يُرجع approve القيمة 'defer' أو لا يوجد callback approve. الـtool لا تعمل. يُحفظ الـrun بالحالة 'awaiting-approval'، ويُرجع execute() (أو resume()):
  • status: 'awaiting-approval' وsuccess: false، بدون error
  • approvalId: المعرّف الذي يجب اتخاذ القرار بشأنه
  • pendingApproval: { approvalId, nodeId, toolName, args }، وهو الاستدعاء المنتظر للقرار
الإيقاف ليس فشلاً، فلا يُطلق step-error ولا flow-error ولا يُعاد. إذا كانت الخطوة المتوقفة داخل عقدة parallel، تُلغى الفروع الشقيقة. الخطوات التي أكملتها تُحفظ، والباقي يعمل من جديد عند الاستئناف. للمتابعة، مرّر القرار إلى resume():
ما يفعله كل قرار:
  • الموافقة: الخطوة المتوقفة تشغّل الـtool بالـarguments المحفوظة، ولا يُسأل approve مرة أخرى.
  • الرفض: الخطوة تفشل بـLOUSHO_FLOW_TOOL_DENIED، تماماً كما لو رجّع approve القيمة false.
  • يُستخدم مرة واحدة: بعد استئناف واحد، لا ينتظر الـrun تلك الموافقة بعد الآن. أي استئناف لاحق يشغّل الخطوة من جديد، فيحتاج قراراً جديداً.
استدعاءات الاستئناف هذه تُرفض:
  • استئناف run متوقف بدون approval: LOUSHO_SESSION_AWAITING_APPROVAL.
  • استئناف بـapprovalId مختلف، أو بموافقة لـrun غير متوقف: LOUSHO_APPROVAL_NOT_FOUND.
موافقات الـflow لا تظهر في الـapproval store الخاص بالـagent. احتفظ بالـapprovalId (أو اقرأ checkpoint.flow.pendingApproval من الـstore) لتتخذ القرار لاحقاً.

خطوات الموافقة

خطوة approval هي بوابة بشرية قائمة بذاتها، دون حاجة إلى استدعاء tool. الـmessage الخاصة بها (بعد تعويض placeholders {{variable}}) هي ما يُسأل عنه الموافِق، والـcallback approve في الـcontext هو الذي يقرّر، تماماً كما في toolCall تحتاج موافقة. الـcallback يرى استدعاءً toolName فيه هو 'flow_approval' وargs فيه هي { message, stepId } (وstepId هو id العقدة، أو موضعها في الـflow).
  • إذا رجّع approve القيمة true (أو ملاحظة) يكمل الـflow، وoutputVariable يأخذ true. أما false فتفشّل الخطوة بـLOUSHO_FLOW_TOOL_DENIED، وكذلك 'defer' وغياب approve في run غير متين (الفشل بالإغلاق).
  • في run متين، 'defer' أو غياب approve يوقف الـflow بنفس طريقة إيقاف toolCall (الإيقاف بانتظار الموافقة): pendingApproval.toolName هو 'flow_approval' وpendingApproval.args.message هي الرسالة بعد التعويض. استأنفه بالقرار:

تشغيل agent داخل flow

خطوة agent تستدعي بالاسم agent من createAgent() مسجّلاً في خريطة agents الخاصة بالـcontext. الـagent يشغّل حلقته الخاصة — الـmodel والـtools والـguardrails والـapprovals الخاصة به — والخطوة تخزّن نص رده:
  • input هو الرسالة المرسلة إلى الـagent، وتُعوَّض فيها placeholders {{variable}} (الافتراضي '{{input}}'، أي متغير input الخاص بالـflow).
  • خطوة agent تُطلق الـevents llm-call وllm-response وفيها data.agent (لا data.model)، وتأخذ retry وtimeoutMs مثل أي خطوة أخرى. ردّها يُخزَّن كنص؛ واستهلاك الـagent موجود في نتيجة send() الخاصة به، لا في result.usage الخاص بالـflow.
  • الخطوة التي تسمّي agent غير موجود في agents تفشل بـLOUSHO_FLOW_INVALID، وتسمّي المفاتيح المسجّلة.
  • الـagent الذي يتوقف الـrun الخاص به بانتظار موافقة (tool عليها needsApproval بلا موافِق) يفشّل الخطوة بـLOUSHO_FLOW_EXECUTION_FAILED: خطوات الـagent لا تستطيع إيقاف flow. قرّر في tools الـagent بالصلاحيات أو بـcallback approve على الـagent.
  • عند التتبّع، يتداخل مقطع التتبّع (span) invoke_agent الخاص بالـagent تحت span flow.node agent الخاص بالخطوة.
بقية خطوات الـflow ما زالت تعمل تحت config الـagent البسيط في الـcontext ({ name, prompt?, settings })؛ وتمرير agent مبني بـcreateAgent() كـcontext.agent يُرفض بـLOUSHO_CONFIG_INVALID. بدلاً من خطوة agent، يمكنك تسجيل tool تستدعي agent.send() واستدعاؤها في خطوة toolCall — عندها يمر الاستدعاء عبر بوابات الصلاحيات والموافقة في الـflow، ويمكن أن تكون نتيجته قيمة typed بدلاً من نص:
لاستدعاء model واحد بلا tools، خطوة llmCall أبسط. نوع العقدة step (StepNode، أي { type: 'step', agent, input }) هو شكل تنتجه المحررات المرئية. FlowExecutor لا يشغّله: الـflow الذي يصل إلى عقدة منه يفشل بـLOUSHO_FLOW_INVALID — استخدم خطوة agent.

flow أم sub-agent أم skill؟

استخدم flow إذا كان الـpipeline معروفاً مسبقاً. استخدم sub-agents عندما تريد أن يقرر الـmodel نفسه ما يفوّضه، وskills عندما يحتاج الـagent نفسه تعليمات إضافية لبعض المهام فقط. راجع sub-agent أم skill أم flow؟. الـtracing يغطي الـflows مثل أي run للـagent (راجع Tracing والـobservability).

تعبيرات الـflow

مقيّم تعبيرات صغير مدمج يقيّم شروط فروع oneOf (وشروط فروع عقدة الـrouter في Agent Forge) وتعبيرات عقدة evaluator. المقيّم لا يصرّف ولا يشغّل كود host إطلاقاً: لا يوجد eval ولا new Function ولا vm في src/flows. الـ{{name}} placeholders تُربَط كقيم ولا تُلصَق في نص التعبير: فـ{{score}} >= 90 المجرّد يستخدم قيمة المتغير، وداخل string literal مثل '{{classify}}' === 'refund' يدخل نص القيمة في الـliteral بعد أن يتجزّأ التعبير إلى tokens. وإذا كانت قيمة المتغير فيها علامات اقتباس أو backslashes أو operators — مثل x' === 'x' || 'a — تبقى مجرد بيانات ولا تستطيع تغيير منطق الشرط. المتغير المفقود أو null يصبح string فارغاً داخل الـliteral؛ وإذا استُخدم مجرّداً لا يضيف شيئاً، فـ{{missing}} >= 90 يعطي خطأ syntax ويعتبر الشرط غير متحقق. المقيّم يقيّم التعبير على متغيرات الـflow. الأسبقية، من الأضعف إلى الأقوى: ||، ثم &&، ثم المساواة، ثم العلاقات، ثم + -، ثم * / %، ثم الأحادية، ثم member access. كل ما عدا الصيغ أعلاه غير مدعوم، ويُرفض بـExpressionError يسمّي التعبير وموضع المحرف وقائمة الصيغ المدعومة: أي استدعاء دالة أو method آخر، والإسناد (= و+= و++)، والـternary، وtemplate strings، وliterals للكائنات والمصفوفات، والوصول إلى constructor أو __proto__ أو prototype، والـglobals مثل process وrequire وglobalThis. الوصول ممكن فقط لمتغيرات الـflow نفسه، ولخصائصها هي فقط. سلوك الفشل لم يتغيّر: شرط oneOf الذي لا يمكن تقييمه يُحسب غير متحقق (false)، وتعبير evaluator الذي لا يمكن تقييمه يفشّل الـflow برسالة Failed to evaluate expression: ...، مع تفاصيل ExpressionError.