مسارات العمل
مسار العمل يربط أدوات API عندك في تدفق واحد خطوة بخطوة يستدعيه الوكيل كأداة واحدة. أنت تحدد الترتيب الدقيق، وتمرر استجابة كل خطوة إلى اللي بعدها، وتتفرع بناءً على النتائج، وتتحكم بدقة في ما يستلمه الوكيل في النهاية.
استخدم مسار عمل لما يحتاج طلب العميل الواحد عدة خطوات موثوقة — الوكيل يشغّله بالمدخلات، والتدفق نفسه يعمل بشكل حتمي، بنفس الطريقة في كل مرة.
مثالنا: Balloon Bliss تريد من Bella الإجابة على "وش حالة طلبي؟". يبحث التدفق عن الطلب في واجهة API الطلبات الخاصة بالمحل، ويتحقق إن كان الإجمالي يؤهل للتوصيل المجاني (الطلبات فوق 20 ر.ع. داخل مسقط)، ويرجع إجابة نظيفة في الحالتين. راح نبنيه كمسار عمل اسمه check_order.
أين تجدها
التكاملات ← مسارات العمل في الشريط الجانبي.
كل بطاقة تعرض خطوات مسار العمل ومفتاح تفعيل/تعطيل. اضغط على New workflow لفتح أداة البناء.
أداة البناء
أداة البناء عبارة عن لوحة رسم مرئية. تضيف العقد من شريط الأدوات، وتوصّلها ببعضها، وتضبط كل واحدة في درج جانبي.
أنواع العقد
| العقدة | ماذا تفعل |
|---|---|
| Start | نقطة البداية. تحمل مدخلات مسار العمل — المعاملات اللي يعبّئها الوكيل عند استدعائه. |
| Tool | تستدعي إحدى أدوات API عندك، مع ربط مدخلاتها من مدخلات مسار العمل أو من خطوات سابقة. |
| Internal | تنفّذ إجراءً مدمجاً في المنصة في منتصف التدفق (مثل التسليم أو إرسال وسائط). |
| Transform | تحسب قيمة بين الخطوات — تشذيب نص، تنسيق تاريخ، جمع مصفوفة — بدون استدعاء أي شيء. |
| Loop | تكرّر جسماً لكل عنصر في مصفوفة. |
| Parallel | تشغّل فرعين أو أكثر في نفس الوقت وتنتظرهما كلها. |
| Sub-flow | تستدعي مسار عمل آخر عندك وتستخدم نتيجته. |
| Timer | تنتظر — مدة محددة، أو حتى وقت معيّن — ثم تكمل. |
| Ask | توقف التدفق ليسأل الوكيل العميل عن شيء، ثم تستأنف بإجابته. |
| File | "التحويل إلى ملف" — تحوّل حمولة base64 من خطوة سابقة إلى ملف قابل للتنزيل يقدر الوكيل يرسله. |
| Branch | توجيه شرطي (if/else). تُفحص الحالات من الأعلى للأسفل؛ أول تطابق يفوز، وإلا يُسلَك مسار else. |
| Return | تُنهي مسار العمل برسالة مكتوبة للوكيل — نتيجة واضحة، وليست تفريغاً خاماً للبيانات. |
| End | عقدة نهاية بسيطة للتدفقات اللي ما تحتاج رسالة إرجاع مخصصة. |
بناء check_order خطوة بخطوة
1. سمِّه وأضف مدخل البداية
اكتب الاسم في الترويسة — بصيغة snake_case، مثل اسم الأداة: check_order.
اضغط على عقدة Start وأضف مكوّن إدخال: order_id. هذا ما سيطلبه الوكيل من العميل. تشير إليه الخطوات بـ {{input.order_id}}.
ثم افتح إعدادات مسار العمل (أيقونة الترس بجانب الاسم) واكتب الوصف — به يقرر الوكيل متى يستخدم مسار العمل، فاجعله محدداً:
تحقّق من طلب Balloon Bliss برقم الطلب وأخبر العميل بالإجمالي وعدد العناصر وما إذا كان يؤهل للتوصيل المجاني داخل مسقط. استخدمه لما يسأل العميل عن حالة أو توصيل طلب قائم.
الوصف مطلوب — لن يُقبل الحفظ بدونه.
2. أضف خطوة الأداة
اضغط على Tool في شريط الأدوات واختر أداة API عندك (هنا: order_status_lookup، اللي تستدعي واجهة API طلبات Balloon Bliss).
يعرض الدرج مدخلات الأداة ولوحة البيانات المتاحة بكل ما تقدر تغذّيها به — مدخلات البداية وسمات العميل ($name، $phone، …). اسحب شارة على مدخل، أو اكتب المرجع مباشرة:
هنا نربط مدخل الأداة order_id بـ {{input.order_id}}.
الإشارة إلى مخرجات الخطوات. استجابة كل خطوة متاحة للخطوات اللاحقة بالصيغة {{steps.<step_id>.json.<path>}} — مثلاً {{steps.step_1.json.total}}. استخدم Fetch sample في الدرج لتشغيل الأداة مرة واحدة وتصفّح حقول استجابتها الحقيقية.
3. تفرّع بناءً على النتيجة
أضف عقدة Branch وحالة واحدة:
- الحقل:
steps.step_1.json.total - النوع:
number - الشرط:
≥ - المقارنة بـ:
20
إذا كان إجمالي الطلب 20 ر.ع. أو أكثر، يُسلَك مسار الحالة (توصيل مجاني). أي شيء آخر يأخذ مسار else.
4. اكتب رسائل Return
أضف عقدة Return لكل مسار. رسالة الإرجاع هي ما يقرؤه الوكيل — اكتبها كأنها الإجابة نفسها، مستخدماً العناصر النائبة:
مسار التوصيل المجاني (النتيجة free_delivery):
الطلب
{{input.order_id}}مؤكد. يحتوي على{{steps.step_1.json.totalQuantity}}عنصراً والإجمالي{{steps.step_1.json.total}}ر.ع. — وهو يؤهل للتوصيل المجاني داخل مسقط (الطلبات فوق 20 ر.ع.).
مسار else (النتيجة delivery_fee_applies):
تم العثور على الطلب
{{input.order_id}}: عدد العناصر{{steps.step_1.json.totalQuantity}}، والإجمالي{{steps.step_1.json.total}}ر.ع. تُطبَّق رسوم توصيل 2 ر.ع. على طلبات مسقط تحت 20 ر.ع. — اقترح إضافة صغيرة للوصول إلى التوصيل المجاني.
كل عقدة Return تأخذ أيضاً معرّف نتيجة اختيارياً (يقدر الوكيل يبني عليه) وحقول بيانات منتقاة اختيارية.
5. وصّل واحفظ
وصّل: Start ← خطوة الأداة ← Branch، ثم كل مقبض تفريع إلى عقدة Return الخاصة به. تعرض الترويسة تحققاً حياً — valid تعني أن كل المشاكل محلولة (مدخلات غير مربوطة، عقد لا يمكن الوصول إليها، حلقات دائرية). اضغط على Tidy لترتيب اللوحة تلقائياً، ثم Save.
التعيين لوكيل
حفظ مسار العمل لا يعرضه على أي وكيل. إذا لم يشغّل الوكيل مسار عملك أبداً، فتحقق من هذا التعيين أولاً — هذا أكثر شيء يُنسى.
- اذهب إلى الوكلاء ← (وكيلك) ← مسارات العمل
- فعّل مسار العمل
خطوات مسار العمل تشغّل أدواتها من جهة الخادم — الأدوات نفسها لا تحتاج تعييناً للوكيل. إذا كانت الأداة يجب أن تعمل داخل المسار فقط (مثل order_status_lookup هنا)، اتركها غير معيَّنة في تبويب أدوات الوكيل حتى لا يستدعيها الوكيل مباشرة ويتجاوز منطق التفريع عندك. عيّن الأداة مباشرة فقط عندما يجب أن يستخدمها الوكيل بنفسه أيضاً (مثل search_gift_addons لأسئلة الهدايا).
من وجهة نظر الوكيل، check_order صار مجرد أداة أخرى بمعامل واحد (order_id). لما يسأل Salim "وش حالة الطلب رقم 5؟"، تستدعي Bella مسار العمل مرة واحدة وتجيب من رسالة الإرجاع — لا ترى أبداً استجابة الـ API الخام ولا التفريعات ولا حسبة التوصيل.
الاختبار
اسأل الوكيل المعيَّن في ساحة التجربة (أو دردشة الويب عندك) سؤالاً يطابق الوصف وتأكد أن الرد يستخدم معلومات رسالة الإرجاع. هنا Bella تجيب عبر check_order على موقع Balloon Bliss:
أبعد من سلسلة بسيطة
check_order ثلاث عقد. التدفقات الحقيقية تحتاج أشكالاً أكثر.
Transform — إعادة تشكيل قيمة بدون استدعاء
اختر اسم مخرَج، واختر عملية، ووجّهها لقيمة. العمليات تغطي النصوص (trim، slice، replace، split، regex_extract)، والأرقام (add، round، number_format)، والتواريخ (now، add_days، format_date، days_between)، والمصفوفات (count، sum، filter، join، pluck، first)، والمولِّدات (uuid، random_int).
كل عملية تكتب مخرَجاً مسمّى تشير له مثل أي خطوة: {{steps.step_3.json.delivery_date}}.
استخدمها لتنسيق تاريخ قبل وضعه في رسالة الإرجاع، أو لجمع قائمة بنود — بدل ما تطلب من واجهتك نقطة نهاية ثانية.
Loop — كرّر لكل عنصر
وجّهها لمصفوفة، وأعطها جسماً، وتشتغل مرة لكل عنصر. داخل الحلقة، {{item}} هو العنصر الحالي و{{index}} موضعه. المخرَج مصفوفة results مع count.
| الخيار | ماذا يفعل |
|---|---|
| Max iterations | حد أقصى صارم، ١–٢٥ |
| Continue on error | اجمع الإخفاقات وواصل بدل إيقاف التدفق |
| Stop early when | تعبير على {{result}} ينهي الحلقة عند تحققه |
Parallel — نفّذ عدة أشياء دفعة واحدة
من فرعين إلى خمسة أفرع مسمّاة تشتغل بالتوازي وتلتقي قبل ما يكمل التدفق. المخرَج مفهرس بمعرّف الفرع. وContinue on error يسجّل الفرع الفاشل ويخلي البقية تكمل.
استخدمها لمّا تكون الخطوات مستقلة عن بعض — فحص المخزون وجلب مواعيد التوصيل في نفس الوقت بدل واحدة بعد الثانية.
Sub-flow — استدعِ مسار عمل آخر
يشغّل واحداً من مساراتك الأخرى داخلياً ويرجّع ok وoutcome وmessage وdata. مناسب للمنطق المشترك بين عدة تدفقات — «وثّق هذا العميل»، «ابحث عن طلب» — يُكتب مرة واحدة.
مسار العمل ما يقدر يستدعي نفسه، والتداخل محدود بثلاثة مستويات.
Timer — انتظر
إما تأخير بالثواني (من ١٠ ثوانٍ إلى ٣٠ يوماً) أو وقت UTC مطلق. التشغيل يُركَن ولا يبقى مفتوحاً: يخزّنه Orki ويلتقطه لمّا يحين الوقت. ما فيه اتصال محجوز أثناء الانتظار.
Ask — احصل على إجابة من العميل
توقف التشغيل وتصف ما تريد جمعه. الوكيل يسأل العميل بأسلوبه، ولمّا يرد، يستأنف التدفق والإجابة متاحة كـ {{signal}}.
النص اللي تدخله تعليمة للوكيل — «اسأله عن تاريخ التوصيل المفضّل» — مو رسالة تُرسَل حرفياً.
جعل الخطوات موثوقة
خياران لكل خطوة، في درج الخطوة.
إعادة المحاولة عند الفشل
«Retry on failure — transient network/timeout only.» اضبط Attempts (٠–٥) وBackoff (ms).
الصياغة دقيقة وتستاهل قراءة مرتين: هذا يعيد المحاولة لمشاكل الاتصال وانتهاء المهلة فقط. أما 400 أو 409 من واجهتك فهي إجابة حقيقية، مو عطلاً عابراً، وما يُعاد معها أبداً.
التراجع عند فشل لاحق
«Undo on later failure — rolls this step back if the flow fails afterwards.»
أرفق إجراء تعويض — أداة API، أو أداة داخلية، أو تحويل — وإذا فشلت خطوة لاحقة، ينفّذ Orki إجراءات التراجع بالترتيب العكسي، الأحدث أولاً.
هذا اللي يخلي تدفقاً متعدد الكتابات آمناً. إذا حجز التدفق مخزوناً وأخذ دفعة ثم فشل في حجز مندوب توصيل، يمكن تحرير الحجز والدفعة بدل ما يعلقان بصمت.
إجراء التراجع اللي يفشل يُسجَّل، ولا يُعاد إلى ما لا نهاية. خلّ إجراءات التراجع بسيطة وقابلة للتكرار الآمن — ألغِ بالمرجع، مو بالموضع.
شروط التفريع
المثال استخدم ≥، لكن المجموعة الكاملة متاحة:
| المجموعة | العوامل |
|---|---|
| المساواة | يساوي، لا يساوي |
| الأرقام والتواريخ | >، ≥، <، ≤ |
| النصوص | يحتوي، لا يحتوي، يبدأ بـ، ينتهي بـ، يطابق (مع *) |
| المجموعات | ضمن، ليس ضمن |
| الوجود | موجود، غير موجود، فارغ (null)، فارغ، غير فارغ |
| نتائج الخطوات | الخطوة نجحت، الخطوة فشلت |
| HTTP | الحالة تساوي، الحالة ضمن |
الخطوة نجحت / الخطوة فشلت هما اللي يفوت على الناس — يخلّونك تتفرّع حسب نجاح الاستدعاء السابق، بدل التخمين من محتواه.
الخطوات الداخلية
عقدة Internal تشغّل إجراءً مدمجاً في منتصف التدفق: handover_to_human، resolve_conversation، send_media_to_user، send_products، send_image_carousel، send_interactive_message، send_otp، update_customer_details، search_knowledgebase، product_search، track_order، get_instagram_post، set_follow_up.
كل واحدة موسومة بأثرها على المحادثة — read أو writes أو sends أو terminal.
handover_to_human وresolve_conversation نهائيتان: تغيّران حالة المحادثة، فما يقدر يشتغل شي بعدهما. وصّلهما مباشرة بـ End.
إعدادات مسار العمل
أيقونة الإعدادات بجانب اسم مسار العمل (التلميح: Workflow settings):
- الوصف (مطلوب) — معايير تشغيل الوكيل للمسار.
- مطابقة مرنة للأنواع في الشروط — تسمح لشروط التفريع بمقارنة
"20"(نص) مع20(رقم) بدل الفشل على النوع. - اشتراط رقم هاتف عميل موثَّق — يقيّد مسار العمل بأكمله خلف توثيق الهاتف بـ OTP، مثل خيار الأمان على مستوى الأداة.
- التنفيذ الدائم (Durable execution) — «احفظ كل خطوة عشان تشغيل طويل أو متقطع يقدر يتعافى.» مطلوب لأي تدفق ينتظر.
- التشغيل في الخلفية (async) — «ارجع للوكيل فوراً وسلّم النتيجة كرد استباقي عند الانتهاء.» يستلزم التنفيذ الدائم.
- البيانات الشخصية في الاستجابة — علّم حقول المخرجات اللي تحمل بيانات شخصية.
التشغيل الدائم وفي الخلفية
مسار العمل العادي يشتغل والوكيل ينتظر، ولازم يخلّص خلال ٨٥ ثانية تقريباً.
التنفيذ الدائم يحفظ التقدّم بعد كل خطوة، فيقدر التشغيل ينجو من إعادة تشغيل — وتقدر عقدة Timer أو Ask تركنه دقائق أو أيام وتلتقطه بعدين. أي تدفق يستخدم هذي العقد يحتاجه.
التشغيل في الخلفية يروح أبعد: يُبلَّغ الوكيل فوراً أن التدفق بدأ، ويكمل دوره، وتوصل النتيجة لاحقاً كرسالة استباقية للعميل. استخدمه للشغل اللي ما يصح ينتظره العميل — تقرير ياخذ دقيقة، متابعة ليلية.
سلسلة استدعاءات API تجاوب على سؤال ← ولا واحد. تدفق فيه Timer أو Ask ← التنفيذ الدائم. شغل أطول من صبر العميل ← التشغيل في الخلفية.
البيانات الشخصية في مخرجات مسار العمل
عادةً ما فيه شي تضبطه: كل خطوة هي أداة API، وأي شي تصرّح فيه تلك الأداة تحت البيانات الشخصية في الاستجابة يُطبَّق تلقائياً ويُربَط بمخرجات مسار العمل.
أضف مدخلات هنا فقط للقيم اللي أنتجتها خطوة Transform أو Loop أو Parallel، لأنها ما تُتتبَّع لأداة. راجع إخفاء البيانات الشخصية.
الحدود
مسارات العمل محدودة عمداً عشان ما ينفلت تدفق في منتصف محادثة.
| الحد | القيمة |
|---|---|
| الخطوات لكل مسار عمل | ١٠ |
| الخطوات في التشغيل كاملاً، بما فيها المسارات الفرعية | ٤٠ |
| عمق تداخل المسارات الفرعية | ٣ |
| تكرارات الحلقة | ٢٥ |
| الأفرع المتوازية | ٢–٥ |
| مدة التشغيل (غير الدائم) | ~٨٥ ثانية |
| حمولة «التحويل إلى ملف» | ٥ ميغابايت |
تجاوز أي حد يعطي خطأً، مو اقتطاعاً صامتاً — راجع استكشاف الأخطاء.
أفضل الممارسات
- مهمة واحدة لكل مسار عمل. "التحقق من طلب" و"إلغاء طلب" مساران منفصلان — الوكيل يختار أفضل بين أدوات موصوفة بدقة.
- رسائل Return هي المنتَج. ركّز جهدك فيها: اذكر النتيجة بوضوح وضمّن الأرقام اللي يجب أن يكررها الوكيل.
- تفرّع للفرق الذي يهم العميل، وليس لكل رمز حالة API. نتيجتان أو ثلاث تكفي غالباً.
- استخدم Fetch sample قبل كتابة المراجع — تخمين مسارات JSON هو السبب الأكثر شيوعاً للعناصر النائبة الفارغة.
- الأسماء بصيغة snake_case وتُعرض على النموذج —
check_orderأفضل منworkflow_1.
استكشاف الأخطاء وحلها
- الحفظ لا يستجيب — راجع شارة المشاكل في الترويسة، وتأكد أن الوصف في إعدادات مسار العمل معبّأ.
- عنصر نائب يظهر فارغاً — مسار JSON لا يطابق الاستجابة الحقيقية للخطوة؛ تحقق بـ Fetch sample.
- الوكيل لا يستدعي مسار العمل أبداً — اشحذ الوصف ("استخدمه لما يسأل العميل عن…") وتأكد أنه معيَّن للوكيل ومفعَّل.
- خطوة الأداة تفشل على نطاق جديد — النطاقات الخارجية يجب اعتمادها في القائمة البيضاء؛ راجع الملاحظة في إنشاء أدوات API.
- التشغيل يتوقف بخطأ حد الخطوات أو ميزانية الوقت — التدفق أكبر من أن يُنفَّذ تزامنياً مرة واحدة. اقسم المنطق المشترك إلى Sub-flow، أو فعّل التشغيل في الخلفية.
- «العميل غير موثَّق» — مسار العمل مفعَّل فيه اشتراط رقم هاتف عميل موثَّق والعميل ما أكمل OTP. خلّ الوكيل يوثّقه أولاً، أو أطفئ الاشتراط.
- عقدة Timer أو Ask ما تستأنف أبداً — هذي العقد تحتاج التنفيذ الدائم مفعّلاً في إعدادات مسار العمل.
- خطوة تفشل بشكل متقطع على واجهة بطيئة — أضف إعادة المحاولة عند الفشل. وتذكّر أنها تعيد المحاولة لأخطاء الشبكة وانتهاء المهلة فقط، مو لأخطاء 4xx.
- تدفق فاشل ترك نصف كتاباته قائمة — أضف التراجع عند فشل لاحق للخطوات اللي تكتب.
الخطوات التالية
- إنشاء أدوات API — اللبنات اللي تربطها مسارات العمل
- المصادقة لأدوات API — أرفق بيانات اعتماد بالأدوات اللي تستدعيها خطواتك
- إخفاء البيانات الشخصية — تحكّم بما يراه الذكاء الاصطناعي في مخرجات مسار العمل
- أحداث النظام — ادفع أحداثاً من نظامك الخلفي إلى الوكيل