FlowBuilder، وشغّله بالدالة static FlowExecutor.execute(flow, context, onEvent?).
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) يحسمه الـcallbackapproveفي الـcontext، وله نفس شكلcreateAgent({ approve }). القيمةtrue(أو ملاحظة) تشغّل الـtool. وfalseترفضها بـLOUSHO_FLOW_TOOL_DENIED. وعندما يُرجعapproveالقيمة'defer'، أو لا يوجد callbackapproveأصلاً، يتوقف الـ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'.
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). كل محاولة فاشلة تُعاد تُطلق eventstep-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.
الـ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، بدونerrorapprovalId: المعرّف الذي يجب اتخاذ القرار بشأنه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.
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تُطلق الـeventsllm-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 بالصلاحيات أو بـcallbackapproveعلى الـagent. - عند التتبّع، يتداخل مقطع التتبّع (span)
invoke_agentالخاص بالـagent تحت spanflow.node agentالخاص بالخطوة.
agent البسيط في الـcontext ({ name, prompt?, settings })؛ وتمرير agent مبني بـcreateAgent() كـcontext.agent يُرفض بـLOUSHO_CONFIG_INVALID.
بدلاً من خطوة agent، يمكنك تسجيل tool تستدعي agent.send() واستدعاؤها في خطوة toolCall — عندها يمر الاستدعاء عبر بوابات الصلاحيات والموافقة في الـflow، ويمكن أن تكون نتيجته قيمة typed بدلاً من نص:
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.