تخطّ إلى المحتوى الرئيسي

وكلاء AI

وكيل AI هو كائن مضبوط قابل لإعادة الاستخدام، كالقالب، يقرأ سياقًا محدودًا ويصدر مخرجات منظمة متحققًا منها. ثم تستخدم الرحلة أو مهمة الكتالوج المحيطة تلك المخرجات؛ ولا يرسل الوكيل نفسه أبدًا ولا يتفرع ولا يحدّث سمة ولا يستدعي API.

تجده في الإعدادات → وكلاء AI. يحتاج إنشاء الوكلاء وتعديلهم إلى نطاق الدور settings:write (أو مفتاح API ذي ai_agents:write)؛ ويحتاج العرض إلى settings:read / ai_agents:read.

التوليد فقط: قرر ولا تتصرف​

هذه هي الفكرة الأساسية، وهي مقصودة. وكيل AI ليس روبوتًا مستقلًا يستدعي الأدوات. لا يملك أدوات ولا إجراءات. في كل تشغيل، فإنه:

  1. يقرأ فقط السياق الذي اخترت إشراكه (السمات المحددة والشرائح وحقول الكتالوج وصوت العلامة والتفاعل الحديث).
  2. يطلب من النموذج إنتاج مخرج يطابق مخطط مخرجات صارم حددته.
  3. يتحقق من المخرج ويعيده، مع explanation اختياري لاستدلال النموذج.

كل ما يتصرف بالنتيجة موجود بالفعل في Joryio: رحلتك ترسل الرسالة أو تسلك الفرع أو تكتب السمة؛ ومهمة إثراء الكتالوج تكتب القيمة في حقل. الوكيل يورد القيمة المنشأة فقط. يبقي ذلك الآليات القوية ذات الآثار الجانبية تحت الحواجز التي تثق بها بالفعل (حدود الإرسال والحظر والتفرع)، ويبقي AI ضمن ما يجيده: التوليد واتخاذ القرار.

إنشاء وكيل​

التعليمات​

التعليمات هي هدف الوكيل، أي system prompt الخاص به. تُصاغ بقوالب Liquid بمفردات مساحة عملك والسياق المحدد وقت التشغيل، لذلك يمكنك الإشارة إلى أسماء سمات وأحداث حقيقية. صف ما تريد توليده والقواعد التي يجب اتباعها (النبرة والطول والقيم المسموحة).

أشر إلى الحقول التي تكشفها فعلًا

لا يرى النموذج إلا حقول السياق التي تسردها في محددات السياق. إذا ذكرت تعليماتك اسم حقل (مثل «افحص السعر») لكنه ليس في السياق، فلن يستطيع النموذج التعامل معه. اذكر الحقل المكشوف بالضبط؛ مثلًا «إذا كان series_id أكبر من 1200…». يعرض سجل التشغيل المدخل الدقيق الذي رآه النموذج، ما يجعل اكتشاف ذلك سهلًا.

العلامات​

امنح الوكيل علامات لتنظيم مكتبة الوكلاء وتصفيتها. تأتي العلامات من مجموعة علامات مساحة العمل المشتركة (العلامات نفسها التي تستخدمها في الحملات والرحلات والقوالب)، فتكتمل تلقائيًا أثناء الكتابة ويمكن تصفية قائمة الوكلاء بها. تُحتسب العلامات في واجهة إدارة العلامات مثل أي مورد موسوم آخر.

النموذج: مُدار مقابل BYO​

يعمل كل وكيل على نموذج واحد، يُضبط بطريقتين:

  • مُدار: Joryio Auto. خيار واحد: تختار Joryio تلقائيًا أفضل نموذج مستضاف (وجهده الاستدلالي) لكل تشغيل. لا شيء لضبطه: لا معرّف نموذج ولا مستوى تفكير. تدفع تكلفة الرموز مع هامشنا، وتُفوتر كرصيد واحد لكل تشغيل من Wallet. لا إعداد مفتاح؛ يعمل مباشرة.
  • BYO (أحضر مزودك): مفتاح مزودك الخاص. المزودون المدعومون: Anthropic وOpenAI وGoogle (Gemini) وAzure OpenAI وAWS Bedrock. هنا تحدد معرّف النموذج الفعلي للاستدعاء (مثل claude-opus-4-8 أو gpt-4o أو gemini-1.5-pro). تدفع لمزود LLM مباشرة عن الرموز؛ وتأخذ Joryio رسوم منصة بسيطة ثابتة لكل تشغيل. أضف المفتاح في مفاتيح المزود (انظر أدناه) قبل اختيار BYO.

محددات السياق (ما يمكن للوكيل قراءته)​

السياق اختياري بالانضمام. لا يقرأ وكيل أي شيء عن جهة اتصال أو سجل ما لم تسرده هنا:

  • مفاتيح السمات: سمات جهة الاتصال المطلوب تضمينها.
  • عضويات الشرائح: أعلام للشرائح التي تسردها.
  • حقول الكتالوج: حقول من سجل الكتالوج أو الكيان الجاري إثراؤه.
  • الحقول المطلوبة: مجموعة فرعية من حقول الكتالوج يجب أن تكون موجودة ليعمل الوكيل. أثناء الإثراء، يُتخطى أي صف يفتقد أحدها ولا يُفوتر أبدًا (ويُسجل سبب التخطي). إغناء صف ناقص يهدر تشغيلًا وينتج إجابة أسوأ عادة، لذلك اجعل الحقول التي يحتاجها الوكيل حقًا مطلوبة.
  • صوت العلامة التجارية: ضمّن صوت علامة مساحة العمل ليبدو المخرج متسقًا مع العلامة.
  • التفاعل الحديث: ملخص قصير لنشاط جهة الاتصال الحديث.
  • إخفاء PII: تُدار معلومات التعريف الشخصية عالميًا: علّم سمة على أنها PII ضمن السمات المخصصة فتصبح محجوبة تلقائيًا قبل أن يراها النموذج في كل وكيل.

مخطط المخرجات​

يقيد مخطط المخرجات ما يمكن للنموذج إعادته، فتتلقى العقد اللاحقة شكلًا متوقعًا دائمًا:

  • النوع: string أو number أو boolean أو json.
  • لـ json، قائمة حقول مسماة، لكل منها نوع بدائي (string أو number أو boolean) ووصف اختياري.
  • تضمين تفسير: التقط استدلال النموذج في حقل explanation (أثر رخيص قابل للفحص).

يُرفض المخرج الذي لا يطابق المخطط ويُعامل كفشل (انظر عقد الأخطاء أدناه).

القيمة البديلة​

يحمل كل وكيل قيمة بديلة: القيمة التي تستبدل عند فشل تشغيل لأي سبب. يضمن ذلك ألا تتوقف رحلتك في انتظار النموذج: عند الفشل إما أن تسلك حافة الخطأ الموصلة أو تستمر بالقيمة البديلة.

الحد اليومي​

يحمل كل وكيل حد تشغيل يومي خاصًا به (250,000 افتراضيًا؛ 0 = غير محدود)، أي أقصى مرات تشغيل ذلك الوكيل يوميًا. عند بلوغه، تفشل التشغيلات اللاحقة مغلقة بالنتيجة budget_exceeded (وتأخذ القيمة البديلة/حافة الخطأ)، فتحمي إنفاقك من رحلة منفلتة. يمتلك حسابك أيضًا حدًا يوميًا على مستوى مساحة العمل يجمع كل الوكلاء وتديره Joryio؛ تواصل معنا لرفعه.

الحواجز​

حواجز وقت التشغيل لكل تشغيل: مهلة صارمة (20 ثانية افتراضيًا)، وحد اختياري لـ رموز المخرج القصوى، وما إذا كان يجب إعادة المحاولة عند الأخطاء المؤقتة (حدود المعدل و5xx فقط، وليس مفتاحًا سيئًا أو مخرجًا غير صالح).

إنشاء وكيل من مساعد AI​

يمكنك أيضًا جعل مساعد Joryio يبني وكيلًا لك: صف ما تريد، مثل «وكيل يقرأ سعر المنتج ويكتب مرتفع أو منخفض»، فيقترح وكيلًا جاهزًا للتطبيق. يعرض بطاقة تطبيق تلخص الوكيل؛ ولا يُنشأ شيء حتى تضغط تطبيق. عند التطبيق، يُنشأ الوكيل كمسودة وتحصل على رابط لفتحه في المحرر، لذلك تظل تراجعه وتختبره وتفعله بنفسك قبل تشغيله. تكون الوكلاء التي ينشئها المساعد دائمًا مُدارة (Joryio Auto)؛ ولا يختار المساعد مزود BYO ولا يتعامل مع المفاتيح.

استخدام وكيل في رحلة​

أسقط عقدة وكيل AI في رحلة واختر الوكيل. لكل جهة اتصال، تقرأ العقدة السياق وتشغّل الوكيل وتكتب المخرج في لقطة التنفيذ حتى تستطيع العقد اللاحقة (الرسائل والفروع وتحديثات السمات) الإشارة إليه.

تعرض العقدة حواف نتائج من الدرجة الأولى لتتفرع حسب ما حدث في التشغيل:

  • success: أعاد النموذج مخرجًا صالحًا؛ وهذا المخرج متاح لاحقًا.
  • fallback: فشل تشغيل لكنك لم تصل حافة خطأ محددة؛ تُستخدم القيمة البديلة وتستمر الرحلة.
  • نتائج error: timeout وrate_limited وinvalid_config وbudget_exceeded. كل منها حافة فرع منفصلة في العقدة، فتستطيع وصل كل نتيجة خطأ بمسارها المتميز في Canvas، أو تركها تقع في fallback.

عقد الأخطاء الصريح هذا فارق متعمد: بدل الفشل الصامت إلى null وإجبارك على حماية كل عقدة لاحقة، يتيح لك وكيل AI توجيه «حدث خطأ في الوكيل ← اسلك هذا الفرع» كما في أي قرار آخر.

إثراء الكتالوج​

يمكن للوكيل أيضًا العمل عبر سجلات الكتالوج أو الكيانات المخصصة لتوليد حقل أو تصنيفه: أوصاف المنتجات والعلامات والعنصر التالي الأفضل أو فئة مطبعة. تختار الوكيل والكيان والحقل الهدف الذي يكتب فيه المخرج وفلترًا اختياريًا لتضييق السجلات المعالجة. يُقاس تشغيل كل صف ويُتتبع تمامًا كتشغيل رحلة.

تعمل مهمة الإثراء بصورة غير متزامنة في الخلفية: ترسل مهمة فتعود فورًا بمعرّف مهمة في الطابور، فيعالج كتالوج كبير (حتى 100k صف) خارج مسار الطلب بدل حجبه. ثم تستطلع المهمة لحالتها وأعدادها؛ وتنتقل الحالة عبر queued → running → completed (أو failed)، وتمتلئ الأعداد (الإجمالي والمعالج والناجح والفاشل والمتخطى) أثناء العمل. المهمة حتمية لكل سجل، لذلك لا تفرض إعادة تشغيلها رسومًا على صف مُغنى مسبقًا. يمكنك تشغيلها ومراقبة تقدمها من لوحة التحكم أو عبر نقاط نهاية الإثراء.

لا تكتب الحقل إلا التشغيلات الناجحة. يُتخطى صف (وتبقى قيمته الحالية دون تغيير) كلما أعاد الوكيل نتيجة غير نجاح: حقل مطلوب مفقود أو Wallet فارغة (budget_exceeded) أو مفتاح BYO مضبوط خطأً (invalid_config) وغيرها. عندما تتخطى صفوف، تعرض المهمة سببًا مثل «لم تُكتب 2 من 2 صفوف: invalid_config: …» لتعرف لماذا لم يُكتب شيء، بدل عدد مجرد. يُفوتر إثراء الكتالوج لكل تشغيل؛ أما الاختبار والمعاينة فمجانيان (انظر أدناه).

الاختبار والمعاينة​

قبل نشر وكيل، استخدم اختبار لتشغيله تجريبيًا على سياق عينة تقدمه (سمات نموذجية وعضويات شرائح وسجل كتالوج وملخص تفاعل). تعيد المعاينة بالضبط ما سينتجه تشغيل حقيقي:

  • outcome: success أو fallback أو إحدى نتائج الخطأ.
  • output: المخرج المنظم المتحقق منه (أو القيمة البديلة عند الفشل).
  • explanation: استدلال النموذج، عند تضمين مخططك له.

تستخدم تشغيلات الاختبار والمعاينة مفتاح تشغيل جديدًا ولا تدخل في رحلة حقيقية وهي مجانية: لا يلزم رصيد Wallet لتكرار الوكيل (ولا تحتاج إلى Wallet ممولة إلا لتشغيلات الرحلات/الكتالوج الحقيقية). إذا أبلغ الاختبار عن نتيجة غير نجاح، يظهر سبب الخطأ الدقيق لتتمكن من إصلاحه (مفتاح مفقود أو Wallet غير ممولة أو مخرج فشل تحقق المخطط وغيرها).

عقد الأخطاء​

ينتهي كل تشغيل بنتيجة واحدة بالضبط:

النتيجةالمعنىأعيدت المحاولة؟
successمخرج صالح يطابق المخطط.-
fallbackفشل تشغيل ولم توصل حافة خطأ محددة؛ تُستخدم القيمة البديلة.-
timeoutتجاوز التشغيل المهلة لكل تشغيل.مؤقت؛ يعاد إن فُعل.
rate_limitedحدّ المزود الطلب.مؤقت؛ يعاد إن فُعل.
invalid_configفشل حتمي: مفتاح سيئ/منتهي أو خطأ ضبط سعر/خصم أو مخرج للنموذج يفشل تحقق المخطط.لا؛ لا يعاد أبدًا.
budget_exceededوصل حد إنفاق: حد تشغيل الوكيل اليومي أو السقف اليومي لمساحة العمل للحساب أو رصيد Wallet غير كافٍ لتشغيل مفوتر.لا.

تستخدم إعادة المحاولة تراجعًا أسيًا محدودًا ولا تنطبق إلا على الإخفاقات المؤقتة.

القياس والتكلفة​

تُقاس التشغيلات لكل استدعاء:

  • مُدار: رصيد واحد لكل تشغيل يُخصم من Wallet. يُسعّر الرصيد مع هامش للرموز زائد هامشنا.
  • BYO: رسوم منصة ثابتة صغيرة لكل تشغيل؛ وتدفع لمزودك عن الرموز مباشرة.

رصيد AI المجاني. يحصل كل حساب على مجموعة شهرية من رصيد AI المجاني (الافتراضي $5/شهر) لا تنفقه إلا تشغيلات وكلاء AI؛ وهي منفصلة عن Wallet الرسائل، لذلك لا تسحب منها SMS/WhatsApp/Email. ينفق كل تشغيل الرصيد المجاني أولًا ثم يعود إلى Wallet المدفوعة عند نفاد الرصيد. يُعاد ضبط الرصيد في بداية كل شهر (استخدمه أو تخسره)، ويظهر رصيده في الإعدادات → الاستخدام. تظل تشغيلات الاختبار والمعاينة مجانية دائمًا مهما كان الرصيد.

تكون الخصومات حتمية حسب معرّف التشغيل، لذلك لا يُخصم من خطوة رحلة معاد تشغيلها مرتين. تُتبع أعداد الرموز والتكلفة الداخلية في كل تشغيل لتقارير الاستخدام.

حدود الإنفاق. يملك كل وكيل حد تشغيل يومي خاصًا به، ويملك حسابك سقف تشغيل AI يومي على مستوى الحساب يجمع كل الوكلاء ومساحات العمل. يمكن لـ Joryio ضبط مبلغ الرصيد المجاني وسقف الحساب لكل حساب؛ تواصل معنا إذا احتجت مساحة أكبر.

سجل التشغيل​

يُسجل كل تشغيل ويمكن استعراضه في شاشة سجل التشغيل الخاصة بالوكيل؛ افتحها من زر التشغيلات في الوكيل في القائمة (صفحة مخصصة لا مخفية في محرر الإعداد). يمكن توسيع كل تشغيل ويعرض:

  • النتيجة وأي سبب خطأ والكمون والتكلفة؛
  • المدخل الذي رآه النموذج: الطلب الدقيق (تعليمات النظام + السياق المحدد المقنّع مسبقًا)؛
  • المخرج الذي أعاده والتفسير الاختياري.

رؤية المدخل الحقيقي بجانب المخرج أسرع طريقة لتصحيح وتحسين وكيل: إذا كانت الإجابة خاطئة، يخبرك المدخل غالبًا لماذا (مثل أن التعليمات أشارت إلى حقل لم تكشفه). يمكنك أيضًا جلب التشغيلات عبر نقطة نهاية التشغيلات.

حوكمة البيانات​

  • PII بالانضمام. لا يرى الوكيل إلا السمات والشرائح والحقول التي تحددها صراحة. لا يصل شيء عن جهة اتصال إلى النموذج افتراضيًا.
  • إخفاء PII عالمي. علّم سمة PII مرة واحدة ضمن السمات المخصصة فتُحجب تلقائيًا قبل وصول السياق إلى النموذج في كل وكيل؛ لا تعيد اختيارها لكل وكيل.
  • يُخزن المدخل مقنعًا للفحص. كي تصحح الوكلاء وتحسنهم، يخزن كل تشغيل الطلب الذي رآه النموذج (النظام + السياق) بعد إخفاء PII ومحدود الحجم. لا يحتوي أبدًا القيم التي علمتها PII. وهذا يشغل سجل التشغيل أعلاه.
  • عزل مساحة العمل. لا يستطيع وكيل قراءة إلا مساحة العمل التي يعمل فيها، وتعيش مفاتيح BYO في مخزن مشفر لكل مساحة عمل؛ ولا تعود قيمها السرية أبدًا عبر API.

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