كيف يشتغل الذكاء الاصطناعي على هذا الموقع: تشريح إنتاجي لـ Mastra

المساعد اللي تحكي معه هو الديمو نفسه

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

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

شكل النظام

المساعد هو مجموعة من وكلاء Mastra، كل واحد منهم له مهمة ضيقة، معروضين عبر مسارات API في Next.js:

• quoteAgent: المساعد الحواري على واجهات عرض السعر والتواصل. يجاوب أسئلة عن الخدمات، يأهّل العميل بشكل طبيعي، ويلتقط العملاء المحتملين.
• chatbotAgent: مساعد خفيف للديمو التفاعلي.
• visionAgent وvoiceAgent وanalyticsAgent: وكلاء مركّزون خلف ساحة لعب الديمو.

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

export const quoteAgent = new Agent({
  name: "quoteAgent",
  instructions: `...`,
  model: MODEL,
  tools: { submitProposal, scheduleCall, draftEmail, sendSummary },
});

هذا الهيكل هو المغزى. الوكيل ما يحتوي منطق العمل. هو يقرر أي أداة يستدعي ومتى. الأدوات هي اللي تحتوي المنطق.

استدعاء الأدوات هو المكان اللي يصير فيه الشغل

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

• submitProposal: التقاط عميل محتمل لمشروع (اسم، إيميل، ملخص).
• scheduleCall: حجز مكالمة مع الفريق.
• sendSummary: إرسال ملخص محادثة بالإيميل.
• draftEmail: تحضير إيميل ليراجعه الفريق.

الانضباط اللي يخلي هذا قابل للاستخدام موجود في الـ prompt: اجمع الحد الأدنى من الحقول المطلوبة، بعدين تصرف. ما في حلقات "هل أكمل؟"، ولا إقرارات فاضية. لما يكون المستخدم أعطى اسم، وإيميل، وملخص مشروع، تنطلق أداة العرض. المستخدم يحصل على نتيجة واضحة، مش طريق مسدود.

اللغة تعيش في سياق التشغيل، مش في الـ prompt

هذا الموقع يصدر بخمس لغات: الإنجليزية، والألمانية، والفرنسية، والإسبانية، والعربية. المساعد لازم يجاوب بلغة الزائر ويحترم السجل اللغوي، مثلاً صيغة Sie الرسمية بالألمانية، ومن اليمين لليسار بالعربية.

الطريقة الغلط لعمل هذا هي تثبيت اللغة داخل الـ system prompt وإعادة بناء prompt لكل لغة. الطريقة الصح هي سياق التشغيل. كل طلب يحمل اللغة، اللي تتحدد من قيمة صريحة، أو هيدر x-i18n-locale، أو هيدر Accept-Language، والوكيل يقرأها وقت التوليد:

const runtimeContext = new RuntimeContext();
if (finalLocale) runtimeContext.set("locale", finalLocale);
runtimeContext.set("requestId", requestId);

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

حالة تتدهور بدل ما تنكسر

تخزين المحادثة يستخدم LibSQL لما يكون رابط قاعدة البيانات مهيأ، ويرجع لتخزين في الذاكرة لما ما يكون كذلك. الاستيراد كسول وملفوف بـ try و catch، فاعتمادية اختيارية ناقصة ما تسقط المساعد أبداً. هو بس يشتغل بدون تاريخ دائم.

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

طبقة الأمان حوالين كل طلب

النموذج هو الجزء السهل. حدود الطلب هي المكان اللي تتأذى فيه ميزات الذكاء الاصطناعي الإنتاجية. كل استدعاء للمساعد يمر عبر نفس البوابات قبل ما يتولّد ولا توكن واحد:

1. التحقق من الطريقة والمدخلات: POST فقط، طول المدخلات محدود، الأجسام المشوهة تُرفض بخطأ مهيكل ومُعرّف طلب.
2. تحديد المعدل: حدود لكل طلب، فالعميل الواحد ما يقدر يستنزف ميزانية الاستدلال.
3. التحقق من المصدر و CSRF: استدعاءات المتصفح لازم تجي من مصدر مسموح وتحمل توكن CSRF صالح. التوكن يُضبط ككوكي ويُفحص على كل استدعاء معدِّل.
4. التفويض الداخلي: الاستدعاءات من خادم لخادم من الباك إند الخاص فينا تتخطى فحوصات المتصفح عبر مسار مصادقة داخلي صريح، مش تجاوز ضمني أبداً.

هذي مش خاصة بالذكاء الاصطناعي. هي نفس البوابات اللي يحتاجها أي نقطة نهاية جدية. الغلطة اللي تعملها الفرق هي معاملة مسار الذكاء الاصطناعي كأنه استثناء وتخطيها. نقطة نهاية الـ LLM لسا نقطة نهاية، وهي تصرف فلوس على كل استدعاء، اللي يخلي تحديد المعدل تحكّم بالتكلفة بقدر ما هو تحكّم بالأمان.

ما في خسارة صامتة للعملاء المحتملين

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

البث، لأن زمن الاستجابة ميزة

الاستجابات تُبث توكن توكن بدل ما تتوقف لين تجهز الإجابة الكاملة. على واجهة مبيعات، زمن الاستجابة المُدرَك هو الفرق بين زائر ينتظر وزائر يمشي. البث يُعالَج في مساعد صغير مخصص فيحصل كل مسار وكيل على نفس السلوك بدون تكرار السباكة.

شو اللي ما بنيناه عن قصد

البنية الجيدة هي كمان قائمة بالأشياء اللي قلت لها لا.

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

هذي القيود تعيش في التعليمات وهي أهم الأسطر في النظام كله. قدرة النموذج محدودة بالحواجز اللي حواليه، وعلى موقع تجاري الحواجز هي المنتج.

الخلاصة لبنائك أنت

إذا كنت تحط ميزة ذكاء اصطناعي في الإنتاج، اختيار النموذج هو القرار اللي بتقضي أقل وقت تندم عليه. اصرف جهدك على الحدود: التحقق، وتحديد المعدل، واللغة، والتدهور اللطيف، ومسار التقاط ما يضيع النية أبداً. أُطر مثل Mastra تعطيك أساسيات الوكيل والأدوات فتقدر تصرف هذا الجهد حيث يجيب ثماره.

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