منشئ الوكلاء

منشئ الوكلاء صفحة واحدة تضم كل ما يحتاج إليه الوكيل، ثم النشر. افتحه من الوكلاء ← وكيل جديد، حيث تختار طريقة البدء: البدء من قالب (السوق)، أو صِفه (المنشئ مع المساعد في الواجهة والشيفرة مطويّة تحت Code)، أو كتابة الشيفرة (المنشئ مع المحرر في الواجهة). وتُفتح الوكلاء المثبّتة من قالب كذلك وشيفرتها مطويّة عند تعديلها؛ وتعرض صفحة الوكلاء جميع وكلاء مساحة العمل. يفتح تعديل الوكيل الصفحة نفسها ويعيد نشر الوكيل ذاته، بالمعرّف نفسه وبأكواد التضمين واستدعاءات الواجهة البرمجية نفسها.

الأساسيات

• الاسم: يظهر في كل مكان داخل backcrew، ويمكنك تغييره لاحقًا.
• النموذج: من النماذج المتاحة لمساحة عملك، مع سعر كل 1,000 رمز. تدفع مقابل النموذج الذي يستدعيه الوكيل فعليًا (راجع «النماذج التي يمكن للشيفرة استدعاؤها» أدناه). ويعرض المنشئ أسفل قائمة النماذج تقديرًا لتكلفة الإجابة المعتادة على النموذج المختار بالأرصدة وبالدولار، على أساس 2,000 رمز إدخال و500 رمز إخراج، مع عملية بحث واحدة في المعرفة إذا أرفقت قاعدة معرفة، وبما لا يقل عن الحد الأدنى للطلب. مرّر المؤشر فوق التقدير لترى الافتراض الذي بُني عليه. أما التكلفة الفعلية لكل إجابة فتعتمد على ما تستهلكه حقًا، وتظهر تكلفة كل إجابة تجريبية في صفحة الوكيل.
• المنطقة: حيث يعمل الوكيل، وتبقى ثابتة بعد إنشائه. يجب أن تكون الأدوات وقواعد المعرفة في المنطقة نفسها.

الشيفرة

مشروع Python في محرر متعدد الملفات:

• يعرّف الملف agent.py (أو الملف الذي تحدده نقطةَ بدء) الكائن agent = Agent(...) باستخدام حزمة Strands Agents.
• أضف ملفات أخرى واستوردها بأسمائها.
• يسرد الملف requirements.txt الحزم الإضافية من PyPI، حزمة في كل سطر.

تضيف backcrew البنية المحيطة بشيفرتك: الذاكرة والأدوات والبحث في المعرفة والسياسات وقياس الاستخدام، لتبقى شيفرتك مركّزة على عمل الوكيل.

النماذج التي يمكن للشيفرة استدعاؤها

اقرأ النموذج الذي اخترته من os.environ["MODEL_ID"]. ويمكن لشيفرتك أيضًا استدعاء أي نموذج آخر في قائمة نماذج backcrew (النماذج الظاهرة في المنشئ)، ويُحتسب كل استدعاء بسعر النموذج الذي استُخدم فعليًا. وتُرفض استدعاءات النماذج غير المدرجة في القائمة. وعند إضافة نموذج إلى القائمة، يصبح بإمكان الوكلاء الحاليين استدعاؤه بعد وقت قصير دون إعادة نشر.

كيف يُنفَّذ الطلب

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

شيفرة يرفض النشر قبولها

يُرفض الحفظ أو النشر، مع ذكر الملف والسطر، إذا كانت الشيفرة تتدخل في بيئة التشغيل التي تحيط بها backcrew وكيلك:

• استيراد الوحدة __main__ أو الإشارة إليها (أما الاستخدام المعتاد if __name__ == "__main__": فمقبول)،
• المساس بالدالة _make_api_call في مكتبة عميل HTTP، وهي النقطة التي تقيس بها backcrew استخدام النماذج،
• الإشارة إلى أسماء القياس الداخلية في backcrew،
• التعامل مع بيانات اعتماد الوكيل نفسه: قراءتها، أو توقيع الطلبات يدويًا. فالمكتبات التي يستخدمها وكيلك تصل إلى بيانات اعتماده بنفسها، ولا تحتاج شيفرتك إلى ذلك أبدًا.

تبدأ رسالة الخطأ بالنص “This code changes how backcrew runs and bills your agent, which isn’t allowed: agent.py line 12: …” (هذه الشيفرة تغيّر طريقة تشغيل backcrew لوكيلك واحتساب تكلفته، وهذا غير مسموح). لا تحتاج شيفرة الوكيل المعتادة إلى أي من ذلك؛ احذف السطر واحفظ مجددًا.

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

• اسمًا لا تحتويه إحدى وحدات المكتبة القياسية، مثل from decimal import decimal ← “the decimal module has no decimal (did you mean Decimal?)”،
• اسمًا أو ملفًا غير موجود في ملفاتك، مثل from probe.tools import add_mony ← “probe/tools.py has no add_mony (did you mean add_money?)”.

ولا تُفحص الاستيرادات الواردة داخل كتل try أو if (إذ يُسمح لها بالفشل)، ولا الحزم الواردة في requirements.txt.

مساعد الإنشاء

• صِف وكيلك: اشرح ما يجب أن يفعله الوكيل بلغة بسيطة، بالعربية أو الإنجليزية؛ يكتب المساعد الشيفرة ويقترح الأدوات والمعرفة والذاكرة مما تملكه مساحة عملك. تراجع ذلك قبل النشر. وعند البدء من وكيل جديد ← صِفه، ترى أولًا ملخصًا بلغة بسيطة (ما سيفعله الوكيل، وما يستخدمه، وما لن يفعله) مع سياسة مقترحة؛ وينشئ زر Create this agent السياسة إن أبقيت عليها، ثم ينشر الوكيل عبر مراجعة الشيفرة المعتادة. أما Use it, but let me look first فيضع الشيفرة في المحرر بدلًا من ذلك. لا يُنشأ أي شيء قبل أن تؤكد.
• الإصلاح بالذكاء الاصطناعي: بعد تعذّر النشر، أو عند إخفاق طلب بسبب خطأ في شيفرتك، يقرأ المساعد الخطأ ويقترح إصلاحًا، وتراجعه أنت قبل الحفظ.

يُحتسب المساعد بحسب الرموز التي يستخدمها (راجع الأرصدة).

ما يمكن للوكيل استخدامه

الحقل	الوظيفة
الأدوات	أدوات مساحة العمل التي يمكن لهذا الوكيل استدعاؤها.
المعرفة	ما يصل إلى 5 قواعد معرفة يبحث فيها ويستشهد بها.
السياسة	السياسة التي يلتزم بها: موضوعات لا يناقشها وإجراءات لا يقوم بها.
فحوصات الجودة	مجموعة فحوصات تُقيّم عيّنة من إجاباته. معطّلة افتراضيًا.

الإعدادات المتقدمة

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

النشر والحالة

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

لا يؤدي حفظ التغييرات إلى إيقاف وكيل يعمل: تستمر لوحة التحكم والواجهة البرمجية وأداة الموقع وTelegram في تلقي الإجابات طوال الوقت.

مراجعة الشيفرة

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

ما يوقف النشر. المشكلات الأمنية فقط، أي الشيفرة التي تحاول الالتفاف على طريقة backcrew في تشغيل الوكلاء أو قياس استخدامهم أو عزلهم، ومن أمثلتها:

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

الحزم. قبل المراجعة، تُفحص الحزم المدرجة في requirements.txt مقابل قاعدة بيانات عامة للحزم المعروفة بأنها خبيثة. وإذا وُجدت حزمة معروفة بأنها خبيثة يتوقف النشر، وتذكر رسالة الخطأ اسمها؛ احذفها واحفظ مجددًا. وإذا حُدّد إصدار بعينه (==) فإن الفحص يشمل ذلك الإصدار.

تابع الفحوصات أثناء تنفيذها. أثناء النشر أو التحديث، يعرض المنشئ وصفحة الوكيل الفحوصات الثلاثة: فحص الشيفرة ← فحص الحزم ← المراجعة الأمنية، وتظهر علامة اجتياز بجانب كل فحص فور اجتيازه. وإذا أوقف أحدها الإصدار، يُميَّز ذلك الفحص ويظهر السبب أسفله كالمعتاد. وبعد تشغيل إصدار اجتاز المراجعة، تحمل صفحة الوكيل شارة تمت المراجعة · آمن للنشر مع تاريخ المراجعة؛ انقر عليها لفتح المراجعة.

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

وكل ما عدا ذلك إرشادي. تنبّه المراجعة أيضًا إلى ما يلي دون أن توقف النشر:

• الأخطاء البرمجية: الأخطاء، والاستيرادات الخاطئة، وغياب agent = Agent(...)، والأدوات التي تفتقر إلى توثيق أو تحديد للأنواع، والاستدعاءات التي لا مهلة لها.
• الأسرار المكتوبة في الشيفرة: استخدم أداة متصلة أو متغير بيئة بدلًا من ذلك.
• نموذج مكتوب مباشرة في الشيفرة: اقرأ os.environ["MODEL_ID"] بدلًا من ذلك.
• أسماء البنية التحتية: أسماء مزوّدي الخدمات السحابية في موجّه النظام أو في أي شيء يراه المستخدمون.
• إعادة بناء ما توفره backcrew: الذاكرة، والبحث في المعرفة، وعملاء HTTP الذين يحملون بيانات اعتماد.
• الجودة: موجّه نظام مبهم، وأوصاف أدوات غير واضحة.

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

عند تعذّر إجراء المراجعة. يتوقف النشر أيضًا في الحالات الآتية:

• إذا تعذّر إجراء المراجعة: أعد المحاولة لاحقًا، أو تواصل مع دعم backcrew؛
• إذا كان المشروع أكبر من أن يُراجَع (أكثر من نحو 300,000 حرف من الشيفرة)؛
• إذا استنفدت مساحة العمل عدد مراجعاتها اليومي: أعد المحاولة غدًا، أو تواصل مع دعم backcrew.

ولا تُراجَع مجددًا الشيفرة المطابقة لآخر شيفرة رُوجعت لهذا الوكيل واجتازت المراجعة.

إذا رأيت أن الإصدار الموقوف سليم، فتواصل مع دعم backcrew؛ إذ يمكن لفريق backcrew مراجعته واعتماده، فيُنشر عندئذٍ. ولا يمكنك تجاوز نتيجة المراجعة بنفسك.

الإصدارات والعودة إلى إصدار سابق

تحتفظ backcrew بكل إصدار من الوكيل يدخل حيّز التشغيل. افتح صفحة الوكيل واختر تبويب الإصدارات (Versions) لعرضها من الأحدث إلى الأقدم: رقم الإصدار، وتاريخ تشغيله، ومن نشره، ونتيجة مراجعة شيفرته (اجتاز المراجعة، أو اعتمده فريق backcrew، أو لم يُراجَع إذا كانت المراجعة متوقفة). والإصدار الموسوم بـ يعمل (Live) هو الذي يجيب حاليًا. أما الإصدار الذي أوقفته المراجعة أو تعذّر تحديثه فلا يُسجَّل إصدارًا، فلا تضم القائمة إلا الإصدارات التي عملت فعلًا.

يعرض خيار المقارنة بالإصدار الحالي (Compare with current) ما تغيّر بين ذلك الإصدار والإصدار العامل: الإعدادات المختلفة (الوصف، والنموذج، والذاكرة، والأدوات، والمعرفة، والسياسة، وفحوصات الجودة، ومفسّر الشيفرة، والمتصفح)، والأسطر المحذوفة والمضافة في كل ملف.

ويعيد خيار العودة إلى هذا الإصدار (Roll back to this version) نشر شيفرة ذلك الإصدار وإعداداته بعد تأكيدك، ويعمل كما يعمل حفظ أي تعديل:

• يبقى الوكيل نفسه، ويواصل الإجابة بالإصدار العامل حتى يجهز الإصدار السابق، فلا يتوقف عن العمل.
• تخضع الشيفرة مجددًا لـمراجعة الشيفرة كأي تحديث. وإذا أوقفتها المراجعة، تصبح الحالة لم يجتز المراجعة ويواصل الإصدار العامل الإجابة.
• يحتفظ الوكيل باسمه الحالي. وإذا كان الإصدار السابق يستخدم أداة أو قاعدة معرفة أو سياسة أو مجموعة فحوصات جودة حُذفت منذ ذلك الحين، تُرفض العودة؛ وعدّل الوكيل بدلًا من ذلك.
• بعد تشغيله، تظهر العودة إصدارًا جديدًا («عودة إلى الإصدار 1»)، فيمكنك دائمًا التقدّم مجددًا.

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

البدء من السوق

يتحول القالب من السوق إلى وكيل عادي في مساحة عملك: يمكنك تعديله كأي وكيل آخر، وتستهلك طلباته الأرصدة كأي وكيل آخر.

تعمل بعض القوالب مع أدوات، مثل مستودع مستندات أو نظام تذاكر. ولا يمكن للقالب أن يجلب معه اتصالات أو بيانات اعتماد، ولذلك تختار أدواتك الخاصة له عند النقر على Install:

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

إذا تخطّيت أداة اختيارية، يُفتح الوكيل على صفحة تعديله وخانة تلك الأداة في أعلاها، وتُظهر صفحته Not finished (غير مكتمل) إلى أن ترفقها.

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

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

ويعمل القالبان جيدًا مع السياسات الجاهزة بالعربية في صفحة السياسات. وتظهر الإجابات العربية من اليمين إلى اليسار في وحدة التجربة وفي أداة الموقع.

لإعداد قالب Cloud Operations خطوةً بخطوة، راجع وكيل العمليات السحابية.