إنتقل إلى المحتوى الرئيسي

مسارات العمل

مسار العمل يربط أدوات API عندك في تدفق واحد خطوة بخطوة يستدعيه الوكيل كأداة واحدة. أنت تحدد الترتيب الدقيق، وتمرر استجابة كل خطوة إلى اللي بعدها، وتتفرع بناءً على النتائج، وتتحكم بدقة في ما يستلمه الوكيل في النهاية.

استخدم مسار عمل لما يحتاج طلب العميل الواحد عدة خطوات موثوقة — الوكيل يشغّله بالمدخلات، والتدفق نفسه يعمل بشكل حتمي، بنفس الطريقة في كل مرة.

مثالنا: Balloon Bliss تريد من Bella الإجابة على "وش حالة طلبي؟". يبحث التدفق عن الطلب في واجهة API الطلبات الخاصة بالمحل، ويتحقق إن كان الإجمالي يؤهل للتوصيل المجاني (الطلبات فوق 20 ر.ع. داخل مسقط)، ويرجع إجابة نظيفة في الحالتين. راح نبنيه كمسار عمل اسمه check_order.

أين تجدها​

التكاملات ← مسارات العمل في الشريط الجانبي.

Workflows list

كل بطاقة تعرض خطوات مسار العمل ومفتاح تفعيل/تعطيل. اضغط على New workflow لفتح أداة البناء.

أداة البناء​

أداة البناء عبارة عن لوحة رسم مرئية. تضيف العقد من شريط الأدوات، وتوصّلها ببعضها، وتضبط كل واحدة في درج جانبي.

check_order workflow on the canvas

أنواع العقد​

العقدةماذا تفعل
Startنقطة البداية. تحمل مدخلات مسار العمل — المعاملات اللي يعبّئها الوكيل عند استدعائه.
Toolتستدعي إحدى أدوات API عندك، مع ربط مدخلاتها من مدخلات مسار العمل أو من خطوات سابقة.
Internalتنفّذ إجراءً مدمجاً في المنصة في منتصف التدفق (مثل التسليم أو إرسال وسائط).
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، …). اسحب شارة على مدخل، أو اكتب المرجع مباشرة:

Step configuration drawer with data mapping

هنا نربط مدخل الأداة 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.

التعيين لوكيل​

مسار العمل لا يفعل شيئاً حتى تعيّنه

حفظ مسار العمل لا يعرضه على أي وكيل. إذا لم يشغّل الوكيل مسار عملك أبداً، فتحقق من هذا التعيين أولاً — هذا أكثر شيء يُنسى.

  1. اذهب إلى الوكلاء ← (وكيلك) ← مسارات العمل
  2. فعّل مسار العمل

Assigning check_order to Bella

لا تعيّن أدوات مسار العمل أيضاً

خطوات مسار العمل تشغّل أدواتها من جهة الخادم — الأدوات نفسها لا تحتاج تعييناً للوكيل. إذا كانت الأداة يجب أن تعمل داخل المسار فقط (مثل order_status_lookup هنا)، اتركها غير معيَّنة في تبويب أدوات الوكيل حتى لا يستدعيها الوكيل مباشرة ويتجاوز منطق التفريع عندك. عيّن الأداة مباشرة فقط عندما يجب أن يستخدمها الوكيل بنفسه أيضاً (مثل search_gift_addons لأسئلة الهدايا).

من وجهة نظر الوكيل، check_order صار مجرد أداة أخرى بمعامل واحد (order_id). لما يسأل Salim "وش حالة الطلب رقم 5؟"، تستدعي Bella مسار العمل مرة واحدة وتجيب من رسالة الإرجاع — لا ترى أبداً استجابة الـ API الخام ولا التفريعات ولا حسبة التوصيل.

الاختبار​

اسأل الوكيل المعيَّن في ساحة التجربة (أو دردشة الويب عندك) سؤالاً يطابق الوصف وتأكد أن الرد يستخدم معلومات رسالة الإرجاع. هنا Bella تجيب عبر check_order على موقع Balloon Bliss:

Bella answering an order question through the workflow

إعدادات مسار العمل​

قائمة الترس بجانب اسم مسار العمل:

  • الوصف (مطلوب) — معايير تشغيل الوكيل للمسار.
  • مطابقة مرنة للأنواع في الشروط — تسمح لشروط التفريع بمقارنة "20" (نص) مع 20 (رقم) بدل الفشل على النوع.
  • اشتراط رقم هاتف عميل موثَّق — يقيّد مسار العمل بأكمله خلف توثيق الهاتف بـ OTP، مثل خيار الأمان على مستوى الأداة.

أفضل الممارسات​

  • مهمة واحدة لكل مسار عمل. "التحقق من طلب" و"إلغاء طلب" مساران منفصلان — الوكيل يختار أفضل بين أدوات موصوفة بدقة.
  • رسائل Return هي المنتَج. ركّز جهدك فيها: اذكر النتيجة بوضوح وضمّن الأرقام اللي يجب أن يكررها الوكيل.
  • تفرّع للفرق الذي يهم العميل، وليس لكل رمز حالة API. نتيجتان أو ثلاث تكفي غالباً.
  • استخدم Fetch sample قبل كتابة المراجع — تخمين مسارات JSON هو السبب الأكثر شيوعاً للعناصر النائبة الفارغة.
  • الأسماء بصيغة snake_case وتُعرض على النموذج — check_order أفضل من workflow_1.

استكشاف الأخطاء وحلها​

  • الحفظ لا يستجيب — راجع شارة المشاكل في الترويسة، وتأكد أن الوصف في إعدادات مسار العمل معبّأ.
  • عنصر نائب يظهر فارغاً — مسار JSON لا يطابق الاستجابة الحقيقية للخطوة؛ تحقق بـ Fetch sample.
  • الوكيل لا يستدعي مسار العمل أبداً — اشحذ الوصف ("استخدمه لما يسأل العميل عن…") وتأكد أنه معيَّن للوكيل ومفعَّل.
  • خطوة الأداة تفشل على نطاق جديد — النطاقات الخارجية يجب اعتمادها في القائمة البيضاء؛ راجع الملاحظة في إنشاء أدوات API.

الخطوات التالية​