انشر Harness الوكيل إلى السحابة: دورة مكثفة متعددة المسارات

*17 مفهوماً • أربعة مسارات تعلم. مسار القارئ: 3 إلى 4 ساعات من القراءة المفاهيمية الخالصة، بلا إعداد ولا نشر، للقادة الهندسيين والمعماريين الذين يقررون هل يستحق هذا النمط وقت الفريق. مسارات المبتدئ والمتوسط والمتقدم: يوم إلى يومين، ثم 3 إلى 5 أيام، ثم 7 إلى 10 أيام، مع قراءة مفاهيمية وعمق متزايد في نشر الحزمة ذات المكونات الخمسة، وربط قابلية الملاحظة وحزمة التقييمات. اختر مسارك قبل المختبر؛ انظر قسم "أربعة مسارات تعلم" أدناه.*

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

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

هذه الدورة أثقل من سابقاتها من ناحية البنية التحتية. تظهر هذه المصطلحات الثلاثة باستمرار، لذلك من المفيد تعريفها ببساطة أولاً:

• Harness. "عقل" الوكيل وضوابطه: الكود الذي يشغّل حلقة الوكيل، ويختار الأداة التي تُستدعى، ويحفظ الأسرار، ويبقي الحالة بين التشغيلات. لا يشغّل كود الوكيل المولّد بنفسه. في هذه الدورة، يكون الـharness تطبيق FastAPI يعمل في السحابة.
• Sandbox. مساحة عمل منفصلة ومغلقة يعمل فيها الكود الذي يولّده الوكيل فعلاً. تستطيع قراءة الملفات وتشغيل أوامر shell، لكنها لا تملك وصولاً إلى أسرار الـharness أو قاعدة بياناته. الصناديق الرملية رخيصة الإنشاء، تُستخدم مرة واحدة، ثم تُرمى.
• Manifest. وصف قصير لما يحتاجه الصندوق الرملي: أي ملفات تُركّب، وأي تخزين يُرفق، وأي قدرات، مثل shell ونظام الملفات، تُفعّل. تصف مساحة العمل مرة واحدة، ثم يستطيع OpenAI Agents SDK تشغيلها على أي مزود صندوق رملي مدعوم.

هناك مصطلحان آخران يتكرران كثيراً ويعرفهما المسرد الكامل: Azure Container Apps، وهي خدمة سحابية مُدارة تشغّل حاويتك مع التوسع التلقائي وعنوان ويب عام، وNeon Postgres، وهي قاعدة Postgres بلا خادم مع تفريع رخيص. المسرد الكامل قسم أدناه.

النسخة المبسطة، ابدأ هنا إذا أردت النسخة البشرية أولاً. (يمكن للقراء التقنيين الانتقال إلى "تعلّم هذه الدورة نشر الإنتاج..." أدناه).

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

تعلّم هذه الدورة نشر الـharness الإنتاجي لـ OpenAI Agents SDK في السحابة. بنت الدورات السابقة معمارية الشركة المعتمدة أصلاً على الذكاء الاصطناعي، ثم لفّتها بالانضباط الذي يجعلها موثوقة بقياس واضح. هذه الدورة تشحن ذلك كله.

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

ما الذي تغيّر في أبريل 2026، ولماذا توجد هذه الدورة الآن. أصدرت OpenAI تحديثاً كبيراً لـ Agents SDK في 15 أبريل 2026 يفصل harness الوكيل عن حوسبة الصندوق الرملي كجزء أصيل من الـSDK. قبل هذا الإصدار، كانت الفرق التي تنشر وكلاء إنتاجيين تجمع يدوياً بين عملاء النماذج، وبيئات تشغيل الحاويات، وعزل الاعتمادات، والحالة، وتوجيه الأدوات. حوّل إصدار أبريل فصل الـharness عن الصندوق الرملي إلى بدائية مدمجة، لا إلى نمط تعيد الفرق اختراعه. لذلك أصبحت هذه الدورة قابلة للتدريس: قبل سنة كانت ستكون في معظمها افتراضية؛ الآن أصبحت وصفة.

المصدر: OpenAI، "The next evolution of the Agents SDK"، 15 أبريل 2026.

مكسب سريع: شغّل الـharness على حاسوبك في نحو 15 دقيقة

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

أولاً، نزّل ملف zip المرافق وفك ضغطه. افتح المجلد في وكيل البرمجة لديك، مثل Claude Code أو OpenCode أو ما يشبههما. يقرأ الوكيل ملف AGENTS.md في الجذر، وهو يشرح كيف بُني المشروع وكيف يُشغّل. ثم الصق التعليمة أدناه.

الصق هذا في وكيل البرمجة. خطط أولاً؛ نفّذ بعد الموافقة.

Read AGENTS.md, then boot Maya's harness locally so I can see it run.

1. Run the SDK probe at the end of AGENTS.md to confirm the installed openai-agents version and that the core imports work.
2. Install dependencies (make install) and copy .env.example to .env. Do not add any keys yet; the harness must boot without them.
3. Start the harness (make run, which serves on http://localhost:8000).
4. In a second shell, request GET /health and show me the exact response.

ينتهي القرار عندما:

• يبلّغ وكيل البرمجة عن نسخة openai-agents المثبتة، والمتوقع 0.17.x.
• يبدأ الـharness ويبقى عاملاً بلا أي مفاتيح مضبوطة.
• يعيد GET /health هذه الاستجابة بالضبط:

{
  "status": "ok",
  "model": "gpt-5.4-mini",
  "backends": { "postgres": false, "sandbox": false, "r2": false }
}

هذه الاستجابة هي الـharness وهو يقول الحقيقة: إنه حي ("status": "ok")، ويعرف نموذجه، ولا توجد أي واجهة خلفية اختيارية موصولة بعد، لذلك كلها false. كل قرار لاحق يقلب واحداً من هذه الأعلام إلى true. يبدأ الـharness بكوده وحده، ثم تضيف قطعة واحدة كل مرة.

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

---

أربعة مسارات تعلم، اختر مسارك

تعمل هذه الدورة على أربعة أعماق مختلفة. اختر مسارك صراحة قبل المختبر؛ صُمم المحتوى المفاهيمي ليناسب المسارات الأربعة، وصُمم المختبر للمسارات 2 إلى 4.

المسار	الالتزام الزمني	ما تكمله	لمن يناسب
القارئ، مفاهيمي فقط	نحو 3 إلى 4 ساعات، بلا مختبر	المكسب السريع، وكل المفاهيم السبعة عشر، والخاتمة. لا حسابات سحابية، لا Docker، لا إعداد Python. تثبت المعمارية؛ ويؤجل النشر.	القادة الهندسيون، ومعماريو المنصات، ومالكو منصات ML الذين يقررون هل يستحق هذا النمط وقت الفريق.
المبتدئ	نحو يوم إلى يومين، مفاهيم ومختبر محلي	مسار القارئ مع مسبار SDK، والهيكلة الأولية، والتحويل إلى حاوية. يعمل الـharness محلياً داخل Docker، ويتحدث إلى OpenAI وقاعدة بيانات محلية. لا نشر سحابياً بعد.	المهندسون الجدد على نشر خدمات الذكاء الاصطناعي في السحابة. الهدف هو ترسيخ فصل الـharness عن الصندوق الرملي وشحن وكيل محوّى يعمل من البداية إلى النهاية على حاسوب.
المتوسط	نحو 3 إلى 5 أيام	مسار المبتدئ مع النشر إلى السحابة، وربط الحالة المتينة، وربط تخزين الملفات، وربط قابلية الملاحظة. يخدم الـharness مستخدمين حقيقيين؛ ويبقى الصندوق الرملي مؤجلاً أو مبسطاً؛ وتؤجل حزمة التقييمات إلى المتقدم.	الفرق التي تريد نشر الـharness وملاحظته، لكنها لا توصل تنفيذ الكود أو انضباط التقييمات كاملاً بعد.
المتقدم	نحو 7 إلى 10 أيام	مسار المتوسط مع ربط الصندوق الرملي، وربط حزمة التقييمات، وقائمة الإنتاج. الانضباط الكامل: harness منشور، وصندوق رملي موصول، وقابلية ملاحظة حية، وحزمة تقييمات تحرس CI وتعمل ليلاً.	فرق الإنتاج التي تشحن مسار النشر الكامل من البداية إلى النهاية، مع قابلية الملاحظة وضمان الجودة.

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

لمحة عن Sprint

إذا أنجزت المسار المتقدم كـSprint مركز من أسبوعين، فهذا هو الإيقاع. يفترض مهندساً واحداً يعمل 4 إلى 6 ساعات منتجة يومياً؛ ويمكن للفرق ضغطه. اليوم الخامس هو نقطة "قابلة للشحن" الطبيعية: الـharness منشور ويخدم المستخدمين. تضيف الأيام 6 إلى 10 التقوية التي تجعل النشر قابلاً للتشغيل على المدى الطويل.

اليوم	التركيز	الناتج التراكمي
1	المفاهيم 1 إلى 4 والهيكلة الأولية	تطبيق FastAPI محلي مع نقطة /runs مبسطة.
2	التحويل إلى حاوية والنشر	Harness يمكن الوصول إليه من الإنترنت العام ومن هاتفك.
3	ربط Neon Postgres	حالة متينة تصمد بعد إعادة تشغيل الحاوية.
4	ربط Cloudflare R2	تخزين ملفات؛ يستطيع الوكيل قراءة المدخلات وكتابة المخرجات.
5	⭐ نقطة قابلة للشحن	Harness منشور يستطيع المستخدمون الحقيقيون استخدامه. توقف هنا إذا كان MVP هو هدفك الوحيد.
6	ربط الصندوق الرملي	تنفيذ الكود يعمل؛ والوكيل يشغّل الكود بأمان.
7	ربط قابلية الملاحظة	تنتقل من تنبيه بنية تحتية إلى سلوك الوكيل بسرعة.
8-9	ربط حزمة التقييمات	لا يشحن أي تراجع في الوكيل من دون أن تلاحظه CI؛ وتعمل تقارير السلوك الليلية.
10	قائمة الإنتاج والتسليم	Harness جاهز للإنتاج وفريق يستطيع تشغيله.

النصفان. القرارات 1 إلى 6 هي دورة النشر الأساسية: تنتج harness عاملاً ومنشوراً مع تنفيذ كود. القرارات 7 إلى 9 هي تقوية الإنتاج: قابلية الملاحظة، وحزمة التقييمات، وانضباط الأمن ودفتر التشغيل. تستطيع الفرق تحت الضغط شحن 1 إلى 6 أولاً، ثم إضافة التقوية خلال الأسابيع التالية؛ التقوية ضرورية فعلاً للإنتاج، لكنها قابلة للإضافة بعد أن يصبح الـharness حياً.

ما الذي سيكون لديك في النهاية

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

تنتج مسارات المبتدئ والمتوسط والمتقدم مخرجات ملموسة. بحسب مسارك، ستكون قد بنيت:

• Harness FastAPI يغلّف OpenAI Agents SDK، من المبتدئ فما فوق: يعمل محلياً ويقدّم API تقبل مهام الوكيل وتعيد النتائج.
• صورة حاوية، من المبتدئ فما فوق: صورة بحجم إنتاجي مناسبة للنشر السحابي.
• الـharness منشوراً إلى Azure Container Apps، من المتوسط فما فوق: مع عنوان عام، وأسرار، وتوسع تلقائي، وتاريخ مراجعات.
• Neon Postgres كمخزن حالة متينة، من المتوسط فما فوق: مخطط للجلسات، والتشغيلات، والتتبعات، والآثار، وسجل تدقيق؛ وهجرات تحت تحكم الإصدارات؛ وتجميع اتصالات.
• Cloudflare R2 للملفات والآثار، من المتوسط فما فوق: bucket مع وصول بروابط presigned من الصندوق الرملي، وتنظيف دورة حياة.
• تنفيذ كود داخل صندوق رملي، في المتقدم: يركّب الـharness Manifest، ويوفّر الصندوق الرملي مساحة عمل، وتعود الآثار عبر R2.
• قابلية ملاحظة عبر أربع واجهات، من المتوسط فما فوق: تتبعات البنية التحتية وتتبعات الوكيل، مع run_id مشترك للتنقل بينها.
• حزمة التقييمات موصولة من البداية إلى النهاية، في المتقدم: بوابة CI للانحدار، وتقارير سلوك ليلية، وخط تتبع إلى تقييم.
• قائمة إنتاج مكتملة، في المتقدم: تدوير الأسرار، ونشر أزرق/أخضر، ودفتر تشغيل للمناوبة، ونسخ احتياطي واسترداد، وحدود معدل، وتنبيهات تكلفة.

كل مسار مكتمل داخلياً: لا يعتمد ناتج مسار المبتدئ على ناتج من مسار أعلى.

مفردات ستقابلها في هذه الدورة

المسرد، اضغط للتوسيع

• Harness. مستوى التحكم للوكيل: الكود الذي يشغّل حلقة الوكيل، ويحفظ الأسرار، ويبقي الحالة. في هذه الدورة هو تطبيق FastAPI في السحابة. لا يشغّل كود الوكيل المولّد.
• Sandbox. مستوى التنفيذ للوكيل: مساحة عمل معزولة يعمل فيها الكود الذي يولده الوكيل، بلا وصول إلى أسرار الـharness أو قاعدة بياناته.
• Control plane / execution plane. المبدأ الذي يضع تنسيق الوكيل، أي الأسرار، والوصول إلى قاعدة البيانات، ومفاتيح النموذج، في حد أمني مختلف عن المكان الذي يعمل فيه كود الوكيل المولّد. هذا أساس هذه الدورة.
• Manifest. وصف قصير لمساحة عمل الصندوق الرملي: تركيبات الملفات، والتخزين المراد إرفاقه، والقدرات المراد تفعيلها. قابل للنقل بين مزودي الصناديق الرملية المدعومين.
• Container. حزمة مغلقة لتطبيقك مع كل ما يحتاجه للعمل، حتى يعمل بالطريقة نفسها على حاسوبك وفي السحابة.
• FastAPI. مكتبة Python لبناء Web APIs. اختيار هذه الدورة لطبقة HTTP في الـharness لأنها تناسب عميل Python غير المتزامن في الـSDK.
• Azure Container Apps (ACA). خدمة سحابية مُدارة تشغّل حاويتك مع توسع تلقائي، وعنوان عام، وأسرار، ومراجعات. بيئة تشغيل الـharness في هذه الدورة.
• Neon Postgres. قاعدة Postgres بلا خادم مع تفريع رخيص. مخزن الحالة المتينة في هذه الدورة.
• Cloudflare R2. تخزين كائنات متوافق مع S3 حيث تكون قراءة ملفاتك الخاصة مجانية. مخزن الملفات والآثار في هذه الدورة.
• Presigned URL. رابط ويب قصير العمر يسمح للصندوق الرملي بقراءة ملف محدد أو كتابته في التخزين، من دون أن يحمل كلمة مرور التخزين أبداً.
• Durable state. ذاكرة تصمد بعد إعادة التشغيل: الجلسات، وتاريخ التشغيل، وسجل التدقيق، محفوظة في قاعدة بيانات بدلاً من الحاوية التي تنسى كل شيء عندما تتوقف.
• Observability. الأدوات التي تخبرك بما يفعله الـharness العامل، ومتى يتعطل شيء، وكيف تجد السبب.
• OpenTelemetry (OTel). معيار مفتوح لتتبع طلب وهو يتحرك عبر الخدمات.
• Phoenix. أداة تراقب تتبعات الوكيل وتحول الحالات السيئة إلى اختبارات مستقبلية.
• Eval. اختبار يقيس سلوك الوكيل، هل كانت الإجابة صحيحة، والأداة صحيحة، والاستدلال سليماً، لا مجرد هل اشتغل الكود.
• Blue/green. طريقة لشحن نسخة جديدة بلا توقف: شغّل النسخة الجديدة بجانب القديمة، ثم حوّل المرور إليها.
• Scale-to-zero. عندما لا توجد حركة، تشغّل السحابة صفر نسخ من تطبيقك ولا تدفع شيئاً؛ وينتظر أول طلب بعد فترة هدوء ثواني حتى تستيقظ نسخة.
• Connection pooling. مجموعة مشتركة من اتصالات قاعدة البيانات المفتوحة يُعاد استخدامها عبر الطلبات، حتى لا تنهار قاعدة البيانات تحت آلاف الاتصالات في الوقت نفسه.

هل أنت جاهز؟

قبل أي شيء: التنزيل المرافق. ملف zip المرافق هو المدخل للجميع، وخصوصاً القراء المستقلين الذين لم ينجزوا الدورات السابقة.

نزّل deploying-agents-crash-course.zip وفك ضغطه. يحتوي على هيكل مشغّل للـharness، FastAPI مع الـSDK وعملاء مبسطين، وملف AGENTS.md الذي يقرأه وكيل البرمجة، وملف schema.sql للجداول الخمسة، وDockerfile، وسكربت نشر Azure، وMakefile للأوامر الشائعة. الوكيل المبسط داخله، Maya's Tier-1 Support agent، هو ما يجعل المختبر يعمل حتى إذا لم تكن قد بنيت Maya بنفسك، فيجد مسار المحاكاة شيئاً حقيقياً يشير إليه.

افتح المجلد في وكيل البرمجة قبل متابعة القراءة إذا كنت تنوي اتباع أي مسار بعد القارئ. القراءة فقط تكفي لمسار القارئ.

0. نزّلت ملف zip المرافق، انظر النداء أعلاه. تجاوز هذا إذا كنت في مسار القارئ ولا تخطط لتشغيل شيء.
1. أنت مرتاح على سطر الأوامر. تستطيع تثبيت الحزم، وتشغيل بضعة أوامر، والتنقل في نظام الملفات. إذا لم تستخدم Terminal من قبل، فمسار القارئ هو المدخل المناسب.
2. تستطيع قراءة كود Python. الـharness مكتوب بـ Python؛ سترى async def وawait وdecorators وtype hints. لا تحتاج إلى خبرة عالية؛ القدرة على القراءة تكفي.
3. لديك مفتاح OpenAI API مع وصول إلى Agents SDK، من مسار المبتدئ فما فوق. هذا حساب النموذج، لا حساب الدردشة فقط. تحقق من platform.openai.com.
4. لديك حساب Azure، من مسار المتوسط فما فوق. ينشر المختبر إلى Azure Container Apps؛ وتكفي الاعتمادات المجانية للمختبر. تحقق من portal.azure.com.
5. لديك حساب Neon، من مسار المتوسط فما فوق. الطبقة المجانية كافية. تحقق من console.neon.com.
6. لديك حساب Cloudflare مع تفعيل R2، من مسار المتوسط فما فوق. طبقة R2 المجانية كافية للمختبر. يحتاج Cloudflare sandbox إلى خطة Workers مدفوعة، لذلك يستخدم المختبر طبقة E2B المجانية كالمسار المجاني الواقعي لتنفيذ الكود.

إذا كانت الحسابات السحابية ناقصة لديك، فمسار القارئ هو نقطة البداية الصحيحة فعلاً: اقرأ أولاً وسجل لاحقاً. وإذا كانت الدورات السابقة ناقصة لديك، فالوكيل المبسط في ملف zip المرافق هو جسر العبور، لذلك يمكنك متابعة المختبر من دون أن تكون قد بنيت Maya بنفسك.

الحواف الخشنة التي ينبغي معرفتها مقدماً

• الكود هنا قابل للتتبع إلى مرافق مشغّل. يطابق كود الـSDK في هذه الدورة الـharness داخل التنزيل، وقد ثُبّت وشُغّل ضد حزمة openai-agents الحقيقية قبل شحن الدورة. هذا ليس كوداً "توضيحياً غير مختبر".
• الـSDK يتحرك بسرعة. إصدار أبريل 2026 هو أول إصدار يجعل هذا النمط قابلاً للتدريس، وستستمر واجهات harness/sandbox في التطور. لذلك أول خطوة في المختبر هي قرار مسبار: يثبت وكيل البرمجة الـSDK، ويطبع النسخة المثبتة، ويجلب الوثائق الحية، ويوفق ملف التوجيه المرافق معها. عندما يختلف الملف عن الوثائق الحية، تفوز الوثائق الحية.
• Python فقط. يشحن إصدار أبريل 2026 ميزات الـharness والصندوق الرملي في Python فقط. دعم TypeScript مخطط لكنه بلا موعد. إذا كان تطبيقك بـ TypeScript، فشغّل Python harness كخدمة منفصلة يستدعيها تطبيق TypeScript عبر HTTP.
• سحابة واحدة، صندوق رملي واحد، قاعدة بيانات واحدة، مزود تخزين واحد. تلتزم هذه الدورة بحزمة محددة حتى تستطيع تعليم مسار كامل. تنتقل المبادئ إلى سحب أخرى بوضوح؛ لا تستعرض الدورة البدائل، مع أن المفهوم 9 والمفهوم 15 يسمّيان أهمها.
• التكلفة حقيقية. يكلف harness منشور بالكامل نحو عشرات الدولارات شهرياً للاستخدام الشخصي منخفض الحركة، ويصل إلى المئات لحركة إنتاج متوسطة. مسارا القارئ والمبتدئ بلا تكلفة؛ أما المسارات السحابية فلها فواتير حقيقية. يشرح المفهوم 13 التفصيل.
• لا تعدد مناطق. تنشر هذه الدورة في منطقة واحدة. يضيف النشر النشط-النشط متعدد المناطق تعقيداً تشغيلياً يستحق معالجة منفصلة؛ ويسمي المفهوم 14 ذلك بصدق.

TL;DR، الادعاءات الأربعة التي تدافع عنها هذه الدورة

1. يجب نشر الـharness والصندوق الرملي كمستويين منفصلين. وضع الـharness داخل الصندوق الرملي مريح للنماذج الأولية، لكنه معمارية خاطئة للإنتاج. يملك الـharness الأسرار، والحالة، والتنسيق؛ ويملك الصندوق الرملي التنفيذ. يعيشان في حدود أمنية مختلفة. يجعل إصدار SDK في أبريل 2026 هذا الفصل جزءاً مدمجاً من الـSDK.
2. مسار كامل واحد أفضل من خمسة استعراضات. الحزمة ذات المكونات الخمسة، FastAPI وAzure Container Apps وNeon وR2 ومزود صندوق رملي، وصفة متماسكة؛ وكل مكوّن استحق مكانه لأنه يؤدي دوراً لا تؤديه المكونات الأخرى. تعمل وصفات أخرى؛ لكنك تتعلم أسرع عندما تسير في واحدة حتى النهاية.
3. تكلفة السحابة جزء من المعمارية. Harness يتوسع بجمال لكنه مكلف جداً للتشغيل مشكلة حقيقية. تسمي هذه الدورة التكلفة كهم من الدرجة الأولى، في المفهوم 13. تهيمن API النموذج على الفاتورة في كل المقاييس؛ والبنية التحتية السحابية شريحة صغيرة.
4. يندمج انضباط التقييمات مع هذا النشر. يربط القراران 7 و8 قابلية الملاحظة وحزمة التقييمات بالـharness الحي. يعتمد ربط حزمة التقييمات على دورة التطوير المدفوع بالتقييمات، أما الغلاف التشغيلي، أي التنفيذ المتين، وإعادة المحاولة، وبوابات الموافقة البشرية، فهو مجال دورة عامل الإنتاج.

شكل ما تبنيه

تقدم هذه الدورة 17 مفهوماً وتمشي عبر 9 قرارات نشر. قبل أي من ذلك، هذه هي المعمارية كلها في صورة واحدة. ارجع إليها كلما بدا مفهوم أو قرار مجرداً.

---

تمهيد الحزمة: ما هو كل مكوّن فعلاً

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

تمهيد الحزمة 1: Docker والحاويات

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

المشكلة التي تحلها هي أقدم شكوى في البرمجيات: "يعمل على جهازي". سكربت Python يعمل على حاسوبك بحزمك الدقيقة قد لا يعمل على حاسوب زميل أو خادم سحابي من دون كثير من العبث. تختصر الحاوية ذلك العبث: ابنِ الصورة مرة، وشغّلها حيث يوجد محرك حاويات.

المفردات التي ستقابلها في المختبر:

• Dockerfile هو وصفة بناء الحزمة: ملف نصي بسيط يقول "ابدأ من هذه القاعدة، انسخ هذه الملفات، شغّل هذه الأوامر".
• Base image هي نقطة البداية، غالباً نظام Linux صغير مع لغة مثبتة مسبقاً. يبدأ الـharness من python:3.12-slim.
• Multi-stage build يستخدم صورة لبناء التطبيق، مع المترجمات والأدوات، وصورة أخرى أصغر لتشغيله، مع الناتج فقط. تبقى صورة التشغيل صغيرة لأن أدوات البناء لا تُشحن معها.
• Registry هو مكان تخزين الصور المبنية ومشاركتها. تدفق النشر هو: ابنِ الصورة، ادفعها إلى registry، تسحبها السحابة وتشغّلها.

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

تمهيد الحزمة 2: FastAPI

FastAPI مكتبة Python لبناء Web APIs: برامج تستمع لطلبات عبر الشبكة وترد ببيانات، غالباً JSON. هي "Fast" لأنها تستخدم ميزات Python غير المتزامنة للتزامن، و"API" لأنها مبنية لنمط الطلب والاستجابة، لا لرسم صفحات ويب.

المشكلة التي تحلها: يعمل وكيلك على خادم، لكن المستخدمين الحقيقيين أو الخدمات الأخرى يحتاجون إلى الوصول إليه من مكان آخر عبر الشبكة. FastAPI هي ما يحوّل كود Python إلى شيء تستطيع الشبكة الحديث معه.

المفردات التي ستقابلها في المختبر:

• Endpoint مسار محدد تتعامل معه API، مثل POST /runs لبدء مهمة أو GET /health لفحص أن الـharness حي.
• Route handler دالة Python تعمل عندما تُستدعى نقطة نهاية. تعلّمها بـdecorator مثل @app.post("/runs").
• async def وawait كلمتا Python للكود الذي ينتظر. يستخدمهما الـharness لأن معظم عمله انتظار: انتظار النموذج، وقاعدة البيانات، والصندوق الرملي. يسمح الكود غير المتزامن لعملية واحدة بمعالجة مئات الطلبات المنتظرة في الوقت نفسه.
• Pydantic models أصناف Python تصف شكل بيانات الطلب والاستجابة. يستخدمها FastAPI لفحص الطلبات الواردة تلقائياً ورفض المشوه منها قبل أن يعمل كودك.
• Uvicorn هو البرنامج الذي يشغّل تطبيق FastAPI فعلاً ويربط الشبكة بالمعالجات. تبدأه بأمر مثل uvicorn maya_harness.main:app.

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

تمهيد الحزمة 3: Neon Postgres

قاعدة البيانات تخزن البيانات على القرص حتى تصمد بعد إعادة التشغيل، وتدعم قراء وكتاباً كثيرين في الوقت نفسه، وتسمح لك بالاستعلام بلغة اسمها SQL. Postgres قاعدة بيانات مفتوحة المصدر محددة، من أوسع القواعد استخداماً في العالم. Neon يشغّل Postgres لك كخدمة، مع ميزتين: بلا خادم، أي يتوسع وينكمش وحده، ويدعم التفريع، أي تستطيع صنع نسخة من قاعدة بياناتك تشارك التخزين مع الأصل حتى تغيرها.

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

المفردات التي ستقابلها في المختبر:

• Table مجموعة مسماة من سجلات منظمة، مثل جدول صارم الأنواع في كل عمود. لدى الـharness خمسة جداول: الجلسات، والتشغيلات، والتتبعات، والآثار، وسجل التدقيق.
• Schema تعريف كل الجداول وأعمدتها.
• Primary key العمود الذي يعرّف كل صف على نحو فريد؛ وforeign key عمود يشير إلى المفتاح الأساسي في جدول آخر، وهذا ما يجعل البيانات علائقية.
• Migration سكربت SQL مُرقّم يغير المخطط، ويُلتزم في المستودع حتى يُتتبع كل تغيير.
• Connection pooling مجموعة مشتركة من الاتصالات المفتوحة يُعاد استخدامها عبر الطلبات. من دونها يفتح كل طلب اتصالاً جديداً، وPostgres له حد. يوفر Neon endpoint مجمعاً ينجز هذا multiplexing نيابة عنك.

النموذج الذهني الأدنى: يخزن Postgres البيانات في جداول ذات أشكال صارمة، وتستعلم عنه بـSQL. يتحدث الـharness إليه عبر مكتبة Python اسمها asyncpg. يستضيف Neon قاعدة البيانات ويضيف التوسع بلا خادم والتفريع فوقها.

تمهيد الحزمة 4: Cloudflare R2

تخزين الكائنات خدمة لتخزين الملفات على الإنترنت. تعطيها اسماً، أو "key"، وبعض البايتات، فتخزنها؛ ولاحقاً تطلب البايتات بالاسم وتستعيدها. أول خدمة من هذا النوع كانت AWS S3، وأصبحت API الخاصة بها معياراً فعلياً تطبقه مزودات كثيرة. Cloudflare R2 هو تخزين كائنات Cloudflare. يطبق API الخاصة بـS3، مع فرق واحد: قراءة ملفاتك الخاصة منه مجانية. تكلف قراءة البيانات من S3 نحو تسعة سنتات لكل غيغابايت؛ ومن R2 لا تكلف شيئاً.

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

المفردات التي ستقابلها في المختبر:

• Bucket حاوية مسماة للملفات، مثل مجلد علوي. يحمل bucket الخاص بالـharness آثار الوكيل.
• Object ملف مخزن واحد، له key، أي مساره في bucket، وقيمة، أي البايتات.
• Prefix جزء من key يجمع ملفات مرتبطة، مثل inputs/ أو outputs/.
• S3-compatible تعني أن R2 يتحدث API نفسها التي ابتكرها S3، لذلك أي مكتبة Python تتحدث إلى S3 تتحدث إلى R2 بتغيير إعداد واحد: endpoint URL.
• Presigned URL رابط قصير العمر يمنح وصولاً إلى كائن محدد واحد. يحتفظ الـharness بالاعتمادات الجذرية؛ وعندما يحتاج الصندوق الرملي إلى ملف واحد، يعطيه الـharness رابطاً presigned بانتهاء صلاحية قصير، فيستطيع الصندوق الرملي الوصول إلى ذلك الملف فقط.
• Lifecycle policy قاعدة تحذف الكائنات الأقدم من عمر محدد، حتى لا يتحول التخزين إلى مقبرة كتابة فقط.

النموذج الذهني الأدنى: R2 مكان يضع فيه الـharness الملفات ويقرأها، عبر API الخاصة بـS3. يحتفظ الـharness بالاعتمادات الجذرية، قراءة وكتابة كل شيء؛ ويحصل الصندوق الرملي فقط على presigned URLs، ملف واحد ووقت قصير.

ما لا تحتاج إليه. لا تحتاج إلى Kubernetes، أو infrastructure-as-code، أو service mesh، أو message broker لإكمال هذه الدورة. تدير الخدمات المُدارة أعلاه الآلات التشغيلية. ولا تحتاج أيضاً إلى طلاقة عميقة في SQL؛ يكفي أن تعرف ما يفعله كود المختبر.

---

الجزء 1: مشكلة النشر

تؤسس ثلاثة مفاهيم سبب وجود هذه الدورة وما تعنيه "مشكلة النشر" فعلاً. يستفيد المبتدئون من هذا التأريض؛ ويستطيع القراء المتقدمون المسح السريع إلى الجزء 2.

المفهوم 1: "يعمل على جهازي" ليس نشراً

لديك وكيل معرّف في Python، لنقل Maya's Tier-1 Support agent: يستدعي أدوات، ويسلّم إلى مختصين، ويحترم حدوده، وينجح في حزمة التقييمات. تشغّله من حاسوبك ويعمل.

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

وهذا ما يعنيه الإنتاج، وكيف تختلف كل قطعة:

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

كم خاصية من هذه الست تستطيع إضافتها إلى سكربت حاسوب محمول بتغييرات صغيرة ويوم أو يومين من العمل؟ الجواب الصادق واحد أو صفر. إضافة أي واحدة منها بطريقة تصمد في الإنتاج تحتاج على الأقل إلى أسبوع من عمل البنية التحتية المركز؛ وإضافة الست كلها هي كامل جسم العمل الذي تعلّمه هذه الدورة. النشر الإنتاجي ليس غلافاً رقيقاً حول "يعمل على حاسوبي". إنه معمارية مختلفة.

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

مشكلة النشر ليست "أين نشغّل السكربت؟". بل "كيف نعيد معمرة الوكيل حتى يملك الـharness هذه الخصائص الإنتاجية الست، بينما يبقى التنفيذ آمناً؟". تعلّم هذه الدورة جواباً كاملاً واحداً.

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

المفهوم 2: فصل الـharness عن الصندوق الرملي، مستوى التحكم مقابل مستوى التنفيذ

أهم فكرة في هذه الدورة هي الفصل بين الـharness، أي مستوى التحكم، والصندوق الرملي، أي مستوى التنفيذ. كل مفهوم وقرار لاحق يستند إليه.

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

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

الحد بينهما حد شبكي وأمني. يتحدث الـharness إلى الصندوق الرملي عبر الشبكة باستخدام اعتمادات الصندوق الرملي؛ ولا يشارك أسراره معه. لا يستطيع الصندوق الرملي قراءة بيئة الـharness أو قاعدة بياناته أو نظام ملفاته. هذا هو انضباط الإنتاج الذي وضعه إصدار SDK في أبريل 2026 داخل الـSDK نفسه.

لماذا يهم هذا الفصل؟ لأربعة أسباب.

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

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

سبب التوسع: يتوسع harness واحد ينسق صناديق رملية كثيرة أفضل بكثير من كتلة harness-plus-sandbox واحدة. احتياجات الـharness متواضعة، فهو يعالج الطلبات، ويستدعي النموذج، ويتحدث إلى قاعدة البيانات؛ أما احتياجات الصندوق الرملي فمتقطعة، مثل ترجمة كود، وتشغيل اختبارات، ومعالجة ملفات. يسمح الفصل لكل واحد أن يتوسع وحده.

سبب قابلية الملاحظة: يملك الـharness السجل. ما قرره الوكيل، وما الأدوات التي استدعاها، وما التتبع الذي أنتجه، كل ذلك يعيش مع الـharness. الصندوق الرملي هو التنفيذ؛ والـharness هو سجل التدقيق. عندما يسوء شيء، سجل الـharness هو ما تقرؤه.

نمطا سوء تتجنبهما هذه الدورة:

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

الخلاصة: يتطلب نشر الوكلاء في الإنتاج فصل الـharness، مستوى التحكم: التنسيق، والحالة، والأسرار، والتدقيق، عن الصندوق الرملي، مستوى التنفيذ: تنفيذ الكود، وعمل الملفات، وshell. الحد بينهما شبكي وأمني. يجعل إصدار SDK في أبريل 2026 هذا الفصل جزءاً مدمجاً من الـSDK. تجنب نمطي سوء: الـharness داخل الصندوق الرملي، وكود الوكيل داخل الـharness.

المفهوم 3: ما الذي يحتاجه الـSDK من البنية السحابية، خمس واجهات

سمى المفهوم 2 النمط. يسأل المفهوم 3: إذا كان هذا هو النمط، فما الذي يحتاجه OpenAI Agents SDK فعلاً من البنية السحابية ليحققه؟ الجواب خمس واجهات، والحزمة ذات المكونات الخمسة تربط كل مكوّن بواحدة منها.

الواجهة 1: خدمة HTTP طويلة العمر لاستضافة الـharness. الـharness عملية Python يجب أن تقبل طلبات المستخدمين، وتبقى عاملة بلا توقف، فقد تستغرق المهمة ثواني أو ساعات، وتتوسع عندما ترتفع الحركة وتتراجع عندما تهبط، وتصمد بعد فشل المضيف. يوفر FastAPI على Azure Container Apps ذلك. يغطي المفهوم 4 FastAPI؛ ويغطي المفهوم 5 Azure Container Apps.

الواجهة 2: حالة متينة عبر التشغيلات. يحفظ الـharness الجلسات، والتشغيلات، والتتبعات، والموافقات، وسجل التدقيق. يوفر Neon Postgres ذلك: Postgres لأنها أفضل قاعدة معاملات مفهومة، وNeon لأن توسعها بلا خادم وتفريعها يطابقان أنماط نشر الـharness. يغطي المفهوم 6 Neon.

الواجهة 3: تخزين ملفات وآثار يصل إليه المستويان. ينتج الوكلاء ملفات، مثل التقارير والكود والتصديرات، ويستهلكون ملفات، مثل الرفع، ومجموعات البيانات، ومحتوى المعرفة. يجب أن تعيش هذه في مكان يستطيع كل من الـharness والصندوق الرملي الوصول إليه. يوفر Cloudflare R2 ذلك: API متوافقة مع S3، وقراءات مجانية لملفاتك، ودعم أصيل كمصدر تركيب Manifest في إصدار SDK في أبريل 2026. يغطي المفهوم 7 R2.

الواجهة 4: تنفيذ معزول للكود الذي يولده الوكيل. عندما يشغّل الوكيل أمر shell، أو يثبت حزمة، أو ينفذ كوداً، يحتاج ذلك العمل إلى بيت معزول عن أسرار الـharness، يُنشأ عند الطلب، وقادر على قراءة المدخلات من التخزين وكتابة المخرجات إليه. يوفر صندوق رملي لتنفيذ الكود ذلك. تغطي المفاهيم 8 إلى 10 طبقة الصندوق الرملي بعمق.

الواجهة 5: التنسيق الذي يربط الواجهات 1 إلى 4. هذا هو الـSDK نفسه. يشغّل حلقة الوكيل، ويوجه استدعاءات الأدوات، نظام الملفات وshell إلى الصندوق الرملي، واستدعاءات النموذج إلى OpenAI، ويدير Manifest، وينتج التتبعات. يستورد الـharness الـSDK ويستخدم بدائياته؛ ولا يعيد اختراعها.

التركيب: يصل طلب إلى FastAPI على Azure Container Apps. يحمّل الـharness الوكيل والحالة السابقة من Neon. يركّب Manifest يصف مساحة العمل التي تحتاجها المهمة. يطلب من مزود الصندوق الرملي توفير تلك المساحة. يشغّل الـSDK حلقة الوكيل، ويرسل استدعاءات الأدوات إلى الصندوق الرملي، ويسجل التتبع. تذهب الآثار إلى R2؛ ويذهب التتبع إلى Neon. تعود النتيجة إلى المستخدم. هذا التركيب هو الدورة كلها؛ كل مفهوم وقرار يفصل قطعة منه.

لست على Python؟ ميزات الـharness والصندوق الرملي Python-only حتى إصدار أبريل 2026؛ ودعم TypeScript مخطط بلا موعد. إذا كان تطبيقك بـ TypeScript، فشغّل Python harness كخدمة منفصلة واجعل تطبيق TypeScript يستدعي نقاطها عبر HTTP. الـharness الذي تبنيه هذه الدورة هو هذه الخدمة بالضبط.

الخلاصة: يعرّف إصدار SDK في أبريل 2026 خمس واجهات معمارية: خدمة HTTP طويلة العمر، وحالة متينة، وتخزين ملفات، وتنفيذ معزول، وتنسيق. تربط الحزمة ذات المكونات الخمسة، FastAPI على Azure Container Apps وNeon وR2 وصندوق رملي والـSDK نفسه، مكوّناً بكل واجهة. غياب أي واجهة ينتج نظاماً غير قابل للنشر. الغلاف التشغيلي الذي يلتف حول هذا، أي التنفيذ المتين، وإعادة المحاولة، وبوابات الموافقة البشرية، هو دورة عامل الإنتاج.

---

الجزء 2: الحزمة ذات المكونات الخمسة

أسس الجزء 1 النمط؛ ويمشي الجزء 2 عبر جانب الـharness من الحزمة، أي FastAPI وAzure Container Apps وNeon وR2، ولماذا استحق كل مكوّن مكانه. أما المكوّن الخامس، الصندوق الرملي، فله الجزء 3 وحده.

المفهوم 4: FastAPI كطبقة الويب للـharness

يحتاج الـharness إلى أن يكون خدمة HTTP طويلة العمر، وتستطيع أطر Python عدة استضافة واحدة: Flask وDjango وFastAPI وStarlette. اختيار هذه الدورة هو FastAPI، لأسباب محددة بما يكفي لتسميتها.

قصة عدم التزامن: بُني OpenAI Agents SDK حول asyncio في Python. استدعاءات النموذج، والأدوات، والصندوق الرملي كلها استدعاءات await. FastAPI أصيل في عدم التزامن، لذلك تكتب معالجات async def تنتظر الـSDK مباشرة بلا حلول thread-pool. إطار أصيل في التزامن سيعني إنشاء event loop لكل طلب أو تشغيل الـSDK في thread pool: كلاهما يعمل، وكلاهما يضيف احتكاكاً ويفقد تزامناً. استخدم الإطار الذي يطابق نموذج تزامنه اعتمادياتك.

قصة المخطط: يولّد FastAPI مخطط OpenAPI من type hints في معالجاتك. يفيد ذلك بثلاث طرق هنا. تستطيع حزمة التقييمات ضرب نقاط الـharness بطلبات مفحوصة لأن المخطط قابل للقراءة آلياً. يمكن توليد مكتبات عملاء typed لأي لغة، ومنها تطبيق TypeScript من الهامش السابق. ويوثق المخطط API لفريقك ولنفسك مستقبلاً بلا جهد كتابة وثائق منفصل.

قصة Pydantic: يستخدم FastAPI Pydantic لفحص بيانات الطلب والاستجابة، ويستخدمه الـSDK داخلياً أيضاً. يحدث التحقق مرة واحدة عند الحد، بالمكتبة والأنماط نفسها التي يستخدمها الـSDK. تحتاج الأطر الأخرى إلى طبقة تحقق منفصلة؛ ويزيل FastAPI هذا عدم التطابق.

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

ما ليس FastAPI. ليس إطاراً عاماً لكل شيء؛ إذا كنت تحتاج صفحات HTML مرسومة بقوالب أو إدارة بأسلوب Django، فـFastAPI اختيار خاطئ. الـharness خادم API، لا تطبيق ويب. وليس بديلاً عن queue أيضاً: إذا استغرقت مهمة أطول مما ينبغي أن يبقى الطلب مفتوحاً، فلا تبقي الاتصال مفتوحاً لها. يضع الـharness العمل في queue ويدع العميل يعود للسؤال؛ يجهّز المختبر هذا النمط.

في المختبر، سترى نقطة POST /runs الخاصة بالـharness: معالج async def يحمّل الجلسة، ويشغّل الوكيل، ويحفظ التشغيل، ويعيد الرد. الدالة قصيرة لأن FastAPI وPydantic يعطيانك معالجة HTTP، والتحقق، والتسلسل مجاناً، وasync def يسمح لك بانتظار الـSDK مباشرة. النسخة الحقيقية المشغّلة من ذلك الكود موجودة في التنزيل المرافق وفي قرار المختبر، حيث يمكن تتبعها إلى harness يعمل فعلاً.

الخلاصة: FastAPI هو إطار الويب للـharness لأنه أصيل في عدم التزامن، فيطابق أساس asyncio في الـSDK، ويولّد مخططات OpenAPI، فتطابق احتياجات التقييمات والعملاء، ويستخدم Pydantic، فيطابق نماذج الـSDK الداخلية. يزيل الاختيار الاحتكاك في ثلاثة مواضع معاً. لكنه ليس queue للوظائف؛ يستخدم الـharness نمط queue يجهزه المختبر.

المفهوم 5: Azure Container Apps كبيئة تشغيل للـharness

الـharness خدمة FastAPI داخل حاوية تحتاج إلى العمل باستمرار، والتوسع مع الحركة، وحفظ الأسرار بأمان، والصمود عند فشل المضيف. اختيار هذه الدورة هو Azure Container Apps (ACA)، وهي خدمة تضعها Microsoft لهذا الحمل بالضبط.

ما هي: خدمة سحابية مُدارة. تعطيها صورة حاوية وإعداداً؛ فتشغل الحاوية، وتعطيها عنواناً عاماً، وتدير التوسع التلقائي، وتخزن الأسرار، وتتابع المراجعات. لا تدير خوادم، ولا تشغّل Kubernetes يدوياً، ولا تكتب كود بنية تحتية للحوسبة الأساسية. تصرّح بما تريد؛ وACA تحققه.

القدرات الخمس التي يحتاجها الـharness منها:

1. عنوان عام. تعطي ACA كل تطبيق عنوان HTTPS ثابتاً بشهادات مُدارة. لا إعداد خادم ويب، ولا إعداد شهادات، ولا ألعاب DNS.
2. توسع تلقائي. تزيد ACA عدد النسخ العاملة بحسب قواعد تضبطها، غالباً بحسب عدد الطلبات قيد التنفيذ. Scale-to-zero هو ذراع التكلفة: مع غياب الحركة، تشغّل ACA صفر نسخ ولا تدفع شيئاً؛ وينتظر أول طلب بعد فترة هدوء ثواني حتى تستيقظ نسخة.
3. أسرار. تخزن ACA الأسرار وتسمح لك بالإشارة إليها بالاسم في متغيرات البيئة؛ ولا تظهر القيم الحقيقية في الإعداد أو الصورة. هذا أفضل بكثير من ملف مفاتيح على القرص.
4. مراجعات. كل نشر ينشئ مراجعة immutable، ويمكن لـACA تقسيم المرور بين المراجعات بأي نسبة. يجعل ذلك النشر الأزرق/الأخضر والرجوع مدمجين: الرجوع تغيير مرور، لا إعادة نشر.
5. قابلية ملاحظة. تغذي ACA السجلات، والمقاييس، والتتبعات في أدوات مراقبة Azure، فتحصل على معدل الطلبات، ومعدل الأخطاء، والكمون مجاناً؛ ويضيف الـharness تتبعات الوكيل فوق ذلك.

لماذا ACA تحديداً، لا Cloud Run أو Fly.io أو Kubernetes خام؟ ثلاثة أسباب صادقة. تضع Microsoft ACA لهذا الملف تحديداً: APIs داخل حاويات، ووظائف خلفية، وخدمات صغيرة. مراجعاتها وتقسيم المرور فيها من الدرجة الأولى، بينما تعامل خدمات كثيرة الأزرق/الأخضر كإضافة. وscale-to-zero فيها صادق: تشغّل صفر نسخ فعلاً ولا تفوترك، بينما تبقي بعض الخدمات "المُدارة" نسخة دافئة وتفوترك. لدى السحب الأخرى بدائل نظيفة، مثل Google Cloud Run وAWS App Runner؛ الشكل المعماري نفسه، ويغطي المفهوم 9 والمفهوم 15 البدائل.

متى تكون ACA اختياراً خاطئاً: إذا احتجت إلى أكثر من نحو 25 نسخة في الذروة، تصبح حدودها لكل تطبيق محرجة ويكون Kubernetes الكامل أنسب؛ وإذا احتجت إلى active-active متعدد المناطق، فقصة المناطق المتعددة فيها أقل نضجاً، ويسمي المفهوم 14 هذا. حاوية الـharness المنشورة صغيرة، مبنية من python:3.12-slim ببناء متعدد المراحل، وتبدأ بـuvicorn، وتُفحص بنقطة GET /health نفسها التي ضربتها في المكسب السريع.

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

الخلاصة: Azure Container Apps هي بيئة تشغيل الـharness لأنها توفر عنواناً عاماً، وتوسعاً تلقائياً، بما فيه scale-to-zero، وأسراراً، ومراجعات، وقابلية ملاحظة كبدائيات مُدارة، بلا إدارة خوادم أو Kubernetes. تضعها Microsoft لخدمات APIs والحاويات والخدمات الصغيرة، وهو ملف الـharness بالضبط. حد الوصفة نحو 25 نسخة ومنطقة واحدة؛ وبعد ذلك يغطي المفهوم 15 الهجرة.

المفهوم 6: Neon Postgres للحالة المتينة

يحتاج الـharness إلى تذكّر أشياء عبر التشغيلات: تاريخ المحادثة، وسجلات التشغيل، والتتبعات، وسجل التدقيق. يجب أن يصمد كل ذلك بعد إعادة تشغيل الحاوية أو توسعها أو استبدالها. اختيار هذه الدورة هو Neon Postgres.

لماذا Postgres أصلاً، لا Redis أو مخزن مستندات؟ حالة الـharness لها ثلاث خصائص تشير إلى قاعدة علائقية تعاملية. هي علائقية في الشكل: للجلسات تشغيلات كثيرة، وللتشغيلات تتبعات وآثار، لذلك تناسبها المفاتيح الخارجية والـjoins. تحتاج إلى سلامة تعاملية: "علّم هذا التشغيل مكتملاً وأدخل تتبعه وحدّث وقت الجلسة" يجب أن يحدث كله أو لا يحدث أي منه، وهذا ما تعطيه معاملات Postgres مجاناً. وقراءاتها علائقية: "أعطني آخر عشرة تشغيلات لهذه الجلسة مع تتبعاتها" استعلام SQL نموذجي. ذاكرة cache مثل Redis أسرع في lookups بالمفتاح، لكنها الشكل الخطأ لمصدر الحقيقة.

لماذا Neon تحديداً، لا RDS أو قاعدة بيانات على VM؟ قصة serverless: يوسع Neon حوسبته وينكمش تلقائياً، ويمكن أن ينكمش إلى قريب من الصفر عندما يكون الـharness خاملاً، فيطابق نموذج تكلفة بقية الحزمة. تفوترك instance مُدارة تقليدية سواء استعلمت أم لا. قصة التفريع: يسمح لك Neon بصنع فرع من قاعدة بياناتك، نسخة تشارك التخزين مع الأصل حتى تغيرها، وهذا يعطي كل مطور نسخاً وقواعد اختبار لكل PR في ثوان. وهو Postgres، لا تقريب له: SQL نفسها، ومكتبات العملاء نفسها، لذلك يكون الانتقال إلى Neon أو خارجه تغيير connection string.

مخطط الـharness خمسة جداول: sessions لسياق المستخدم المستمر، وruns لكل مهمة وكيل، وtraces للتتبع الكامل من الـSDK لكل تشغيل، وartifacts لمؤشرات الملفات في R2، وaudit log كسجل immutable لما حدث، لحزمة التقييمات والامتثال. ينشئ قرار المختبر 4 هذا المخطط من ملف schema.sql في التنزيل المرافق.

فخان في Neon يصلحهما المختبر لك. يحتوي connection string الذي تنسخه من Neon على channel_binding=require. لا يتعرف برنامج asyncpg على ذلك ويفشل ضد pooled endpoint، لذلك يزيل الـharness channel_binding قبل الاتصال، مع إبقاء sslmode=require. وبشكل منفصل، يسقط pooled endpoint إعدادات search_path بصمت، لذلك يكتب الـharness كل statement بتأهيل المخطط (public.runs وpublic.sessions)، وتشغّل المخطط ضد direct endpoint غير المجمع. كلاهما فخان حقيقيان، ويعالجهما الكود المرافق؛ ويسميهما المختبر كمعايير قبول صريحة.

تجميع الاتصالات ليس اختيارياً. يتوسع الـharness إلى نسخ كثيرة، وكل نسخة تفتح اتصالات، وينهار Postgres فوق بضع مئات في الوقت نفسه. يوفر Neon pooled endpoint يضرب آلاف اتصالات الـharness في عدد صغير من اتصالات Postgres الحقيقية. يتصل الـharness بالـpooled endpoint للعمل العادي، وبالـdirect endpoint فقط لتغييرات المخطط.

الخلاصة: Neon Postgres هو مخزن الحالة المتينة للـharness لأن Postgres هو الشكل الصحيح لحالة علائقية وتعاملية وكثيرة القراءة، وNeon تحديداً لأن توسعه بلا خادم يطابق ACA وتفريعه يعطي قواعد رخيصة لكل مطور ولكل PR. تجميع الاتصالات إلزامي؛ يستخدم الـharness pooled endpoint للتطبيق وdirect endpoint للهجرات. المخطط خمسة جداول، يبنيها القرار 4.

المفهوم 7: Cloudflare R2 للملفات والآثار

يحتاج كل من الـharness والصندوق الرملي إلى ملفات: مستندات مدخلة يقرأها الوكيل، وآثار مخرجة ينتجها، ومحتوى معرفة يسترجعه. اختيار هذه الدورة هو Cloudflare R2، لثلاثة أسباب محددة.

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

لماذا R2 تحديداً، لا S3 أو GCS؟ قصة الخروج هي السبب الرئيسي. قراءة ملفاتك الخاصة من R2 مجانية. يفرض S3 وGoogle Cloud Storage وAzure Blob رسوماً على البيانات المنقولة إلى الخارج، عادة خمسة إلى اثني عشر سنتاً لكل غيغابايت. لوكيل ينقل الملفات بين الـharness والصندوق الرملي مراراً، تتراكم هذه بسرعة. Harness ينقل بضعة تيرابايتات شهرياً سيدفع مئات الدولارات في egress على S3 وصفر على R2؛ وتكاليف التخزين والطلبات متقاربة تقريباً، لذلك يختفي بند egress ببساطة. في harness منخفض الحركة يكون الفرق صغيراً، لكن في الحجم الحقيقي يكون الخروج المجاني الفرق بين قابلية الجدوى وعدمها.

ويتحدث R2 أيضاً API الخاصة بـS3، لذلك تتحدث أي مكتبة Python لـS3 إليه بتغيير إعداد واحد، endpoint URL، بلا إعادة كتابة عميل إذا هاجرت يوماً. ويذكر إصدار SDK في أبريل 2026 R2 كمصدر تركيب Manifest مدعوم بجانب S3 وGCS وAzure Blob، لذلك يعلن الـharness buckets R2 داخل Manifest ويركبها الصندوق الرملي بلا كود جسر مخصص.

يستخدم الـharness ثلاثة prefixes في bucket: inputs/ للملفات التي يرفعها المستخدمون، وoutputs/ للملفات التي ينتجها الوكيل، وknowledge/ لمحتوى المعرفة طويل العمر. يجهز قرار المختبر 5 ذلك.

Presigned URLs هي طريقة حصول الصندوق الرملي على وصول من دون الاعتمادات الجذرية. يحتفظ الـharness بالاعتمادات الجذرية التي تستطيع قراءة أو كتابة أي شيء. لا يشاركها مع الصندوق الرملي. بدلاً من ذلك، يصدر رابطاً presigned لكائن محدد واحد، بانتهاء صلاحية قصير، ويعطيه للصندوق الرملي. يستطيع الصندوق الرملي الوصول إلى ما يسمح به الرابط فقط؛ وعندما يموت، يصبح الرابط بلا قيمة، ويحصل الصندوق التالي على روابط جديدة. هذا هو فصل الاعتمادات من المفهوم 2 مطبقاً: لا يستطيع صندوق رملي مخترق listing buckets أو الوصول إلى بيانات مستخدم آخر.

تمنع سياسات دورة الحياة التخزين من التحول إلى مقبرة كتابة فقط: يضع المختبر تنظيفاً بعد 30 يوماً على outputs/، ولا يضع شيئاً على knowledge/ المنسق.

الخلاصة: Cloudflare R2 هو مخزن ملفات الـharness لأن تخزين الكائنات هو الشكل الصحيح، لا قاعدة البيانات ولا قرص الحاوية، وR2 تحديداً لأن قراءة ملفاتك خارجه مجانية، ما يوفر مئات إلى آلاف الدولارات شهرياً عند الحجم، وAPI المتوافقة مع S3 لا تحتاج إلى هجرة SDK، والـSDK يدعمه كمصدر تركيب Manifest. يستخدم الـharness presigned URLs لمنح الصندوق الرملي وصولاً محدداً بلا اعتمادات جذرية؛ وتنظف سياسات دورة الحياة الآثار القديمة.

---

الجزء 3: مستوى التنفيذ

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

المفهوم 8: قدرات تنفيذ الصندوق الرملي

سمى المفهوم 2 الصندوق الرملي كمستوى التنفيذ: المكان الذي يعمل فيه الكود بلا وصول إلى أسرار الـharness. يجعل المفهوم 8 ذلك ملموساً. ما الذي يحتاجه الوكيل فعلاً من صندوق رملي؟

خمس قدرات:

1. نظام ملفات. يقرأ الوكيل الملفات ويكتبها: مدخلات، وآثاراً وسيطة، ومخرجات. يوفر الصندوق الرملي نظام ملفات شبيهاً بـUnix مع عمليات قراءة وكتابة وتحرير وlisting مكشوفة كأدوات. من دونه، لا يستطيع الوكيل عمل الملفات.
2. Shell. يشغّل الوكيل أوامر: مشغل اختبارات، أو تثبيت حزمة، أو clone، أو أداة مخصصة. يوفر الصندوق الرملي shell تعمل فيه هذه. من دونه، ينحصر الوكيل فيما يغلّفه الـharness صراحة.
3. تثبيت الحزم. يثبت الوكيل الحزم عند الطلب: "ثبت هذه المكتبة، ثم اقرأ الملف الذي رفعه المستخدم، ثم لخّصه". من دونه، تُحبس قدرة الوكيل فيما شحنت به الصورة الأساسية.
4. تخزين مركب. يحتاج الوكيل ملفات أكبر من القرص المحلي: uploads، ومحتوى معرفة، ومجموعات بيانات. يركب الصندوق الرملي تخزيناً خارجياً، R2 أو S3 أو GCS، كمسارات عادية، ويعلن Manifest ما يركب وأين. من دونه، يستطيع الوكيل لمس الملفات الصغيرة بما يكفي للشحن داخل الصورة فقط.
5. Snapshot and resume. الصناديق الرملية قابلة للرمي وقد تفشل وسط التشغيل. يستطيع الصندوق الرملي أخذ checkpoint لحالته والاستئناف من تلك النقطة في مساحة عمل جديدة، وهذا ما يجعل الـSDK المهام الطويلة تصمد عند موت مساحة العمل. من دونه، كل مهمة أطول من عمر الصندوق الرملي فشل ينتظر الحدوث.

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

ما ليس الصندوق الرملي. ليس VM طويل العمر تبقيه عاملاً عبر المهام؛ فهذا يعيد اختراع المشكلة ويراكم الحالة والتشابك مع أسرار الـharness. وليس serverless function تشغّل دالة واحدة وتعود؛ الصندوق الرملي مساحة عمل تصمد عبر استدعاءات أدوات كثيرة داخل تشغيل واحد، وتحفظ حالة في نظام ملفاتها أثناء التشغيل، وتعطي وصول shell. وليس Kubernetes؛ يجرد مزود الصندوق الرملي تنسيق الحاويات كله، فتحصل على العزل والزوال من دون تشغيل cluster.

الخلاصة: يوفر الصندوق الرملي الإنتاجي نظام ملفات، وshell، وتثبيت حزم، وتخزيناً مركباً، وsnapshot-and-resume، مع العزل والزوال وسرعة التوفير كخصائص أساسية. ليس VM طويل العمر، ولا serverless function، ولا Kubernetes. يتوقع إصدار SDK في أبريل 2026 هذه القدرات من أي مزود متوافق.

المفهوم 9: اختيار مزود الصندوق الرملي

سمى المفهوم 8 القدرات؛ ويختار المفهوم 9 المزود. هذه الدورة صريحة في الاختيار وفي المسار المجاني الواقعي.

ابدأ بالمقايضة التي تحسم الأمر لمعظم القراء. يحتاج Cloudflare sandbox إلى خطة Workers مدفوعة، ويحتاج أيضاً إلى bridge Worker صغير بين Python harness والصندوق الرملي. ولدى E2B طبقة Hobby مجانية، وعميل أصيل في الـSDK، ولا يحتاج إلى bridge. لذلك إذا أردت إكمال المختبر بلا دفع، فـE2B هو المسار المجاني الواقعي؛ وإذا كنت بالفعل على خطة Cloudflare مدفوعة وتستخدم R2، فإن Cloudflare sandbox يستحق ميزة القرب. كُتب المختبر بحيث يعمل الاثنان، ويفترض الكود المرافق E2B لأنه الخيار الذي تستطيع اختباره مجاناً فعلاً.

لماذا Cloudflare sandbox هو الاسم الأساسي في الدورة عندما تختاره: يعمل في شبكة Cloudflare، وكذلك R2، لذلك يحدث تركيب buckets R2 بسرعات داخلية في Cloudflare بدلاً من الإنترنت العام. لا يملك أي مزود آخر ذلك القرب من R2. لديه أيضاً دعم SDK من الدرجة الأولى وهيكل تكلفة لا يحسب وقت الخمول، والوكيل ينتظر النموذج أكثر مما ينفذ. العقبة هي الخطة المدفوعة وbridge Worker: العملاء غير Workers، مثل Python harness، لا يستطيعون إنشاء صناديق Cloudflare مباشرة، لذلك يترجم Worker صغير ومنشور منفصل استدعاءات الـharness إلى عمليات صندوق رملي. المزودون الآخرون، ومنها E2B، يكشفون Python API مباشرة ولا يحتاجون إلى bridge.

البدائل الصادقة، ولكل منها حالة استخدام يفوز فيها:

• E2B. المسار الواقعي المجاني ومزود عام مصقول. يعمل جيداً بالتساوي مع S3 أو GCS أو Azure Blob، ولدى الـSDK عميل أصيل له. استخدم E2B عندما تكون حيادياً تجاه التخزين، أو لست على R2، أو تريد إكمال المختبر مجاناً.
• Modal. قوي لأحمال Python ML؛ تشغيل مهام الوكيل بجانب inference مدعوم بـGPU بسيط. استخدم Modal إذا تضمن وكيلك خدمة نموذج مخصص.
• Daytona. يعمل داخل حسابك السحابي. استخدمه للصناعات المنظمة حيث يتطلب توطين البيانات أن يعيش الصندوق الرملي في سحابتك المحددة، مقابل تعقيد تشغيلي أعلى.
• Vercel. استخدمه إذا كان فريقك عميقاً في منظومة Vercel؛ وهو أقل نضجاً للأحمال غير JavaScript.
• Bring-your-own. يدعم الـSDK تنفيذ عميل صندوق رملي على بنية حاوياتك. يستحق ذلك فقط عندما يشترط فريق الأمن أن تكون الصناديق الرملية في سحابتك، نقطة؛ ويرتفع التعقيد التشغيلي كثيراً.

الاستبدال بين المزودين ميكانيكي في الغالب. Manifest محايد للمزود، لذلك تعلن شكل مساحة العمل نفسه أياً كان المزود. يتغير صنف عميل المزود، عميل Cloudflare لأحدهما وعميل E2B للآخر. يختلف تركيب التخزين حسب قرب الشبكة، R2 مع Cloudflare sandbox سريع؛ وR2 مع E2B يمر عبر الإنترنت العام، وهذا ما يزال يعمل. ونمط الاعتمادات متطابق: يحتفظ الـharness باعتمادات المزود ويعطي الصندوق الرملي وصولاً قصير العمر فقط.

التوصية في سطر واحد: استخدم Cloudflare sandbox إذا كنت على خطة Workers مدفوعة وتستخدم R2؛ واستخدم E2B خلاف ذلك، وخصوصاً إذا أردت المسار المجاني؛ اختر واحداً واشحن بدلاً من استعراضها كلها.

الخلاصة: Cloudflare sandbox هو الاسم الأساسي في هذه الدورة لقربه من R2 ودعم SDK من الدرجة الأولى، لكنه يحتاج خطة Workers مدفوعة وbridge Worker. E2B هو المسار المجاني الواقعي: طبقة Hobby مجانية، وعميل SDK أصيل، ولا bridge. يفترض الكود المرافق E2B؛ ويعمل المختبر مع الاثنين. تبديل المزودين ميكانيكي لأن Manifest محايد للمزود.

المفهوم 10: التسليم من الـharness إلى الصندوق الرملي

ينسق الـharness؛ وينفذ الصندوق الرملي. يمشي المفهوم 10 عبر التسليم: كيف يخبر الـharness الصندوق الرملي بما يوفره، وكيف تعبر الاعتمادات الحد بأمان، وكيف تُدار دورة حياة الصندوق الرملي خلال تشغيل.

Manifest هو عقد التسليم. يركّب الـharness Manifest يصف ما تحتاجه مساحة العمل؛ يستقبله المزود ويوفر مساحة تطابقه. في SDK أبريل 2026، يُبنى Manifest من مجموعة entries: كل entry مسار في مساحة العمل مربوط بما يوضع هناك، ملف، أو دليل، أو git repo، أو mount تخزين. تعيش mounts مثل R2Mount وS3Mount وغيرها في agents.sandbox.entries وتدخل داخل تلك entries. لا توجد قائمة منفصلة من mounts ولا حقول base-image أو resource-limit على Manifest نفسه؛ تصف entries مساحة العمل.

from agents.sandbox import Manifest
from agents.sandbox.entries import R2Mount

# Mounts go inside entries, keyed by their path in the workspace.
manifest = Manifest(
    entries={
        "/workspace/inputs": R2Mount(
            bucket="maya-harness-artifacts",
            prefix=f"inputs/{session_id}/",
        ),
        "/workspace/outputs": R2Mount(
            bucket="maya-harness-artifacts",
            prefix=f"outputs/{run_id}/",
        ),
    }
)

تُختار القدرات من افتراضات الـSDK، والقائمة التي تمررها تستبدلها. تعيد Capabilities.default() المجموعة القياسية، أي نظام الملفات وshell وcompaction. إذا مررت قائمة خاصة بك، فإنها تستبدل الافتراضي بدلاً من الإضافة إليه، لذلك إذا أردت إبقاء الافتراضي وإضافة قدرة أخرى، اجمع:

from agents.sandbox.capabilities import Capabilities, Skills

# Keep the defaults and add one: a passed list REPLACES the default,
# so concatenate rather than passing [Skills(...)] alone.
capabilities = Capabilities.default() + [Skills(name="data-tools")]

هذا فخ حقيقي: كتابة capabilities=[Shell()] تسقط بصمت قدرات نظام الملفات وcompaction التي كان الافتراضي يشملها. أبقِ الافتراضي وأضف إليه.

يُرفق الصندوق الرملي عبر RunConfig، لا كوسيط في Runner.run. لا يوجد معامل Runner.run(..., sandbox=...). تبني SandboxRunConfig بعميل المزود وكائن خياراته، وتضعه على RunConfig، وتمرر RunConfig إلى التشغيل. يقترن كل عميل مزود بكائن خياراته، وتدخل الخيارات في SandboxRunConfig لا في constructor العميل:

from agents import Runner
from agents.run import RunConfig
from agents.sandbox import SandboxRunConfig
from agents.extensions.sandbox.e2b import E2BSandboxClient, E2BSandboxClientOptions

# The client reads E2B_API_KEY from the environment; the options carry the
# required sandbox_type. The sandbox rides on RunConfig, not a Runner kwarg.
sandbox = SandboxRunConfig(
    client=E2BSandboxClient(),
    options=E2BSandboxClientOptions(sandbox_type="e2b"),
)
result = await Runner.run(agent, message, run_config=RunConfig(sandbox=sandbox))

لـCloudflare sandbox، الشكل نفسه؛ يتغير العميل والخيارات فقط، CloudflareSandboxClient مع CloudflareSandboxClientOptions(worker_url=...). هذا بالضبط هو الكود في sandbox.py وrunner.py داخل التنزيل المرافق، وقد شُغّل ضد الـSDK المثبت.

انضباط الاعتمادات هو أهم نقطة أمنية. يحتفظ الـharness باعتمادات التخزين الجذرية واعتمادات المزود. يصدر presigned URLs لكائنات محددة، بانتهاء صلاحية قصير، وتدخل تلك الروابط إلى مساحة العمل، لا الاعتمادات الجذرية. يستقبل الصندوق الرملي تلك الروابط المحدودة فقط: لا يستطيع enumeration للـbuckets، ولا الوصول إلى قاعدة بيانات الـharness، فلا يعبر connection string الحد، ولا الوصول إلى خدمات الـharness الأخرى، فسياسة الشبكة تقصره على ما يحتاجه، مثل API النموذج ومستودعات الحزم. أي شيء آخر، مثل وضع اعتمادات جذرية أو database string في مساحة العمل، هو الخطأ الأمني الذي صُمم إصدار أبريل 2026 لمنعه.

دورة الحياة لتشغيل واحد: يستقبل الـharness الطلب ويحمّل حالة الجلسة؛ يركّب Manifest للمهمة؛ يطلب من المزود توفير مساحة العمل؛ يشغّل الـSDK حلقة الوكيل، موجهاً استدعاءات نظام الملفات وshell إلى الصندوق الرملي ومسجلاً التتبع؛ إذا فشلت مساحة العمل وكانت snapshots مفعلة، يوفر الـSDK واحدة جديدة من آخر snapshot ويكمل؛ عند الاكتمال، يقرأ الـharness أي مخرجات من R2، ويحفظ التتبع ومؤشرات الآثار في Neon، ويدمر الصندوق الرملي حتى لا يبقى شيء خاملاً، ويعيد النتيجة إلى المستخدم.

الخلاصة: يجري التسليم من الـharness إلى الصندوق الرملي عبر Manifest مبني من entries تصف مساحة العمل، وتعيش mounts في agents.sandbox.entries. تأتي القدرات من Capabilities.default()، والقائمة الممررة تستبدله. يُرفق الصندوق الرملي عبر RunConfig(sandbox=SandboxRunConfig(client=..., options=...))، لا عبر وسيط في Runner.run. لا تعبر الاعتمادات الجذرية الحد أبداً؛ يستقبل الصندوق الرملي presigned URLs محدودة فقط. دورة الحياة: توفير، تشغيل، snapshot-and-resume عند الحاجة، ثم تدمير. هذا هو فصل الاعتمادات من المفهوم 2 مطبقاً.

---

الجزء 4: قابلية الملاحظة والتقييمات كواجهات معمارية

نشرت الأجزاء 1 إلى 3 الـharness. سيبنيه مختبر الجزء 5. يقع الجزء 4 بينهما ويسمي الواجهتين اللتين لا يزال فصل الـharness عن الصندوق الرملي من الجزء 1 يحتاج إليهما: الأنظمة التي تخبرك بما يفعله الـharness العامل، والأنظمة التي تقيس هل ما زال يفعل الشيء الصحيح. الفرق التي تتجاوز هذه تشحن harness يعمل في اليوم الأول ويتدهور بصمت بعده. مفهومان، ثم المختبر.

المفهوم 11: قابلية الملاحظة كواجهة معمارية

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

عندما يعمل الـharness، تراقبه أربع واجهات في الوقت نفسه. تبدو متشابهة، لكن كل واحدة تملك سؤالاً مختلفاً.

الواجهة	السؤال الذي تملكه
Application Insights	هل بنية الـharness التحتية سليمة؟
OpenTelemetry traces	كيف تدفق طلب واحد عبر الخدمات؟
OpenAI Agents SDK traces	ماذا فعل الوكيل خلال هذا التشغيل؟
Phoenix	كيف يتغير سلوك الوكيل مع الزمن؟

Application Insights مراقب Azure المدمج. يملك رؤية الحاوية: معدل الطلبات، ومعدل الأخطاء، والكمون، وCPU والذاكرة، وعدد إعادة التشغيل، وتدفقات السجلات. عندما تنهار replica، يلاحظ أولاً. لا يرى سلوك الوكيل. بالنسبة إليه، كل طلب هو "POST /runs returned 200 in 12 seconds"؛ هل كانت الإجابة صحيحة فهذا غير مرئي.

OpenTelemetry (OTel) معيار مفتوح لتتبع طلب واحد عبر الخدمات. التتبع هو السجل الكامل لتشغيل واحد. عندما يتفرع طلب واحد إلى استدعاء نموذج، وثلاثة استدعاءات أدوات، وأربعة استعلامات قاعدة بيانات، يعرض OTel توقيت الأبناء والآباء بينها. لا يرى استدلال الوكيل بين استدعاءات الأدوات؛ يسجل أن النموذج استُدعي، لا لماذا.

يصدر OpenAI Agents SDK تتبعه الخاص: أي قرارات نموذجية اتُخذت، وأي أدوات استُدعيت وبأي وسائط، وإلى أين ذهبت التسليمات. يملك رؤية سلوك الوكيل. ولا يرى شيئاً خارج تنفيذ الوكيل.

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

تتداخل الواجهات؛ ولا تستبدل بعضها. ترتبط بـrun_id مشترك، حتى يستطيع الفريق البدء من أي واجهة والقفز إلى أي أخرى بنقرة. ينبه Application Insights إلى ارتفاع في البنية التحتية؛ ويعرض OTel أي span كان بطيئاً؛ ويعرض تتبع SDK ما كان يفعله الوكيل؛ ويعرض Phoenix هل يتكرر النمط نفسه. تجاهل واجهة واحدة وتفقد خطوة كاملة: تجاهل Application Insights فتفوتك الأعطال، وتجاهل OTel فتفوتك الـspan البطيئة، وتجاهل تتبع SDK فتفوتك قرار الوكيل، وتجاهل Phoenix فتتقادم حزمة التقييمات.

الخلاصة: قابلية الملاحظة واجهة معمارية، لا بند checklist، ولها أربع واجهات. يملك Application Insights البنية التحتية، وOpenTelemetry تدفق الطلب، وتتبع SDK تنفيذ الوكيل، وPhoenix الاتجاه مع الزمن. يربطها run_id مشترك حتى ينتقل الفريق من أي عرض إلى سببه. اربط الأربع من اليوم الأول؛ الواجهة الناقصة عمياء بقدر السؤال الذي تملكه.

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

المفهوم 12: التقييمات كواجهة معمارية

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

الحد في مكان واحد: التتبعات. كل ما تقيمه حزمة التقييمات يقرأ من تتبع، والتتبعات تعيش في مخزنين. يحتفظ Neon بالسجل المتين الذي تستعلمه الوظائف المجدولة والتدقيق. ويحتفظ Phoenix بالعينة الفورية المعروضة على اللوحة الحية. إذا أردت تذكر شيء واحد من هذا المفهوم، فتذكر أن التكامل يمر عبر التتبعات، وأن التتبعات تعيش في Neon وPhoenix.

عندما ينتهي تشغيل، يكتب الـharness التتبع إلى Neon تزامنياً، أي السجل المتين، ويرسل عينة إلى Phoenix لا تزامنياً، أي الرؤية الحية. من هناك، تتصل أطر التقييم في نقاط محددة: تعمل بوابة CI على كل pull request، وتقيّم الوظائف المجدولة تتبعات اليوم السابق ليلاً، وتشغّل Phoenix فحوصاً inline عند وصول التتبعات. يربط القرار 8 ذلك كله كاملاً. سبب التخطيط له الآن لا لاحقاً بسيط: التتبعات التي تُنتج قبل ربط قابلية الملاحظة تضيع، وحزمة التقييمات لا تنمو إلا من تتبعات رأتها فعلاً.

الخلاصة: تتصل التقييمات بالـharness المنشور عبر التتبعات، المكتوبة إلى مخزنين. يحتفظ Neon بالسجل المتين القابل للاستعلام؛ ويحتفظ Phoenix بالعينة الفورية. تقرأ أطر التقييم من هاتين الواجهتين. اربط كتابة التتبع من اليوم الأول، لأن التتبعات المنتجة قبل وجود الربط لا يمكن أن تصبح اختبارات انحدار. يبني القرار 8 الربط؛ وهذا المفهوم يثبت الحد فقط.

---

الجزء 5: مختبر النشر

غطت الأجزاء 1 إلى 4 المعمارية والواجهات. يبني الجزء 5 كل شيء: عشرة قرارات تأخذك من مجلد فارغ إلى harness منشور وقابل للملاحظة ومحروس بالتقييمات. الشكل هو نفسه الذي تستخدمه الدورات السابقة. أنت توجه وكيل برمجة؛ والوكيل يكتب الكود ويشغله. كل قرار تعليمات قصيرة تلصقها، وسطر "ينتهي عندما" تستطيع ملاحظته، وملاحظة من سطر واحد للقراء الذين يتابعون بلا نشر.

يحمل التنزيل المرافق السياق المشترك. داخله، يحفظ AGENTS.md قواعد المشروع، والمعمارية، وأشكال API المتحققة، لذلك تبقى كل تعليمة قصيرة: يقرأ الوكيل AGENTS.md للتفاصيل وتلصق أنت الهدف فقط. نزّل الملف الآن: deploying-agents-crash-course.zip.

ارجع إلى هذا المخطط أثناء العمل. يضيف كل قرار قطعة موسومة واحدة.

طريقتان لإكمال المختبر.

البناء الكامل، لمساري المتوسط والمتقدم: تنشر إلى السحابة. اهدم الموارد بعد كل جلسة وفي نهاية المسار فتظل الفاتورة من البداية إلى النهاية صغيرة؛ اتركها عاملة فتكبر. يشرح المفهوم 13 تفصيل التكلفة.

المحاكاة، لمساري القارئ والمبتدئ: تقرأ الكود المرافق بدلاً من provision أي شيء. ما زال الـharness يعمل محلياً بمجرد ضبط OPENAI_API_KEY، لذلك تستطيع تشغيل كل خطوة لا تحتاج إلى حساب سحابي. تشرح ملاحظة المحاكاة في كل قرار ما تقرؤه بدلاً من التنفيذ.

القرار 0: افحص الـSDK ووفق ملف التوجيه

في سطر واحد: ثبت الـSDK، اطبع النسخة المثبتة، اجلب وثائق الصندوق الرملي الحية، ووفق AGENTS.md المرافق معها. تفوز الوثائق الحية.

يشحن OpenAI Agents SDK بسرعة. تنتقل الأسماء، والتواقيع، والافتراضات بين الإصدارات. AGENTS.md المرافق هو المعروف-الصحيح اليوم، لا الصحيح إلى الأبد. لذلك أول قرار مسبار: أكّد كل رمز يعتمد عليه المختبر ضد الـSDK المثبت فعلاً على جهازك، واكتب أي انجراف. خمس دقائق هنا توفر ساعة من "لماذا لا توجد هذه الخاصية" لاحقاً.

الصق هذا في وكيل البرمجة. خطط أولاً؛ نفّذ بعد الموافقة.

Open the companion download. Run the SDK probe from the bottom of AGENTS.md: uv sync, then the import checks for agents, agents.sandbox, agents.sandbox.entries, and the E2B client. Print the installed openai-agents version. Fetch the live sandbox API reference from the official docs. Compare every SDK symbol named in AGENTS.md against what you actually imported. If anything differs, the live docs win: write a short "What changed since the brief" note at the top of AGENTS.md listing each difference, and use the live name everywhere after. Do not change any code yet.

ينتهي القرار عندما:

• يبلّغ الوكيل عن نسخة openai-agents المثبتة، والمتوقع 0.17.x.
• يبلّغ الوكيل عن أي أسماء SDK تختلف عن AGENTS.md، وتفوز الوثائق الحية في كل اختلاف.
• توجد ملاحظة قصيرة "What changed since the brief" أعلى AGENTS.md، أو يصرح الوكيل أن الملف طابق الـSDK المثبت.

مسار المحاكاة. اقرأ قسم مسبار SDK في نهاية AGENTS.md. لا تحتاج إلى تشغيله؛ الهدف هو رؤية عادة مقاومة الانجراف: أكّد ملف التوجيه ضد الـSDK الحي قبل الوثوق بأي رمز، ودع الوثائق الحية تفوز.

الخلاصة: يستند المختبر الآن إلى الـSDK الذي لديك فعلاً، لا إلى النسخة التي كُتب لها الملف. يحترم كل قرار لاحق ملاحظة "What changed". هذه هي الآلية التي تحفظ المختبر صحيحاً مع حركة الـSDK.

القرار 1: هيكل الـharness

في سطر واحد: تطبيق FastAPI فيه الوكيل، وطبقة الحالة، وطبقة التخزين، وكلها تتدهور بأناقة عند غياب مفتاح، ويعمل محلياً على OPENAI_API_KEY وحده.

ينشئ هذا القرار المشروع الذي تبني عليه التسعة التالية. يأتي الوكيل، Maya's Tier-1 Support، وأداتاه من الدورات السابقة؛ هذا القرار هو الـharness الذي يغلّفه، لا الوكيل نفسه.

الصق هذا في وكيل البرمجة. خطط أولاً؛ نفّذ بعد الموافقة.

Scaffold the harness from the companion AGENTS.md. Follow its project rules and architecture exactly. Pin openai-agents>=0.17,<0.18. Build the FastAPI app with GET /health (reports which backends are active) and POST /runs (loads the session, runs Maya's agent, persists the run and trace, optionally writes an artifact). Wire graceful degradation: the app must import and boot with only OPENAI_API_KEY set, falling back to SQLite when DATABASE_URL is unset and to a local directory when no R2 keys are set. Add the two tools (lookup_account, draft_reply) as @function_tool functions whose bodies run in the harness, not the sandbox. Commit the lockfile.

ينتهي القرار عندما:

• يبدأ uv run uvicorn maya_harness.main:app الـharness بلا أخطاء.
• يعيد GET /health قيمة {"status": "ok", ...} مع ظهور postgres وsandbox وr2 كلها false في تشغيل عارٍ لا يضبط إلا OPENAI_API_KEY.
• يعرض GET /docs الـAPI المولّدة تلقائياً للنقطتين.

مسار المحاكاة. يحتوي المرافق هذا الهيكل مسبقاً. اقرأ src/maya_harness/main.py وagent.py وsettings.py، ولاحظ كيف تكون كل واجهة خلفية اختيارية: كل مفتاح ناقص يطفئ مكوّناً واحداً ويبقى الـharness يعمل.

مكسب سريع

ذلك التشغيل هو المكسب المبكر الذي تعد به الدورة كلها. قبل أي حساب سحابي، وأي Docker، وأي قاعدة بيانات، لديك harness حقيقي يجيب على /health من حاسوبك. فصل الـharness عن الصندوق الرملي لم يعد رسماً؛ إنه يعمل على جهازك. كل ما بعده يضيف واجهة خلفية متينة واحدة في كل مرة.

الخلاصة: harness FastAPI عامل مع الوكيل، وحالة اختيارية، وتخزين اختياري، وكلها تتدهور بأناقة. يثبت شكل المشروع هنا؛ وتملأ القرارات التالية الواجهات الخلفية الحقيقية واحدة تلو أخرى.

القرار 2: حوّل الـharness إلى حاوية

في سطر واحد: صورة حاوية صغيرة وقابلة للتكرار للـharness تعمل بالطريقة نفسها على حاسوبك وفي السحابة.

الحاوية: حزمة مغلقة لتطبيقك مع كل ما يحتاجه للعمل، حتى يتصرف بالطريقة نفسها في كل مكان. ينشر القرار 3 هذه الصورة؛ ويبنيها القرار 2.

الصق هذا في وكيل البرمجة. خطط أولاً؛ نفّذ بعد الموافقة.

Build the harness container from the Dockerfile shape in the companion. Use python:3.12-slim with uv for a reproducible install from the committed lockfile. Install dependencies in a cached layer before copying the source. Expose port 8000 and run uvicorn maya_harness.main:app --host 0.0.0.0 --port 8000 --proxy-headers (the --proxy-headers flag matters because the cloud terminates TLS at its ingress). Add a .dockerignore that excludes the virtualenv, caches, and .env files. Build the image and run it locally with your .env mounted.

ينتهي القرار عندما:

• تُبنى الصورة بلا أخطاء.
• تعمل الحاوية محلياً ويعيد GET /health قيمة ok من داخلها.
• تكون إعادة البناء بعد تغيير ملف مصدر سريعة، لأن طبقة الاعتماديات تبقى cached.

مسار المحاكاة. اقرأ Dockerfile المرافق. التمرين هو فكرة multi-stage: تثبت الاعتماديات في طبقة cached، ثم يُنسخ المصدر بعدها، وتبقى الصورة صغيرة. لا تحتاج إلى Docker مثبتاً.

الخلاصة: صورة harness صغيرة وقابلة للتكرار تعمل محلياً وفي السحابة بالطريقة نفسها. هذه الصورة هي بالضبط ما يدفعه القرار 3 إلى Azure.

القرار 3: انشر إلى Azure Container Apps

في سطر واحد: وفّر بيئة تشغيل سحابية مُدارة، وابنِ الصورة في السحابة، وانشر الـharness حتى يجيب من الإنترنت العام عبر HTTPS.

Azure Container Apps (ACA): خدمة مُدارة تشغّل حاويتك في السحابة مع توسع تلقائي وingress، حتى لا تشغّل خوادم بنفسك. هذا القرار هو المكان الذي يغادر فيه الـharness حاسوبك.

الصق هذا في وكيل البرمجة. خطط أولاً؛ نفّذ بعد الموافقة.

Deploy the harness to Azure Container Apps using the infra/deploy.sh shape in the companion. Create a resource group and a container registry. Build the image in the cloud with az acr build (no local Docker needed). Create the Container Apps environment, then create the app with --ingress external, --target-port 8000, and --min-replicas 0 for scale-to-zero. Store OPENAI_API_KEY as a named secret and reference it with secretref:, never baked into the image. Confirm the app's public URL and that /health answers over HTTPS. Pass the current environment through to any subprocess so the keys survive.

ينتهي القرار عندما:

• ينتهي سكربت النشر ويطبع عنوان *.azurecontainerapps.io عاماً.
• يرد فتح https://<that-url>/health من هاتفك بـ{"status": "ok", ...}.
• بعد فترة هدوء، يتوسع التطبيق إلى صفر، ويوقظ الطلب التالي نسخة خلال ثوان قليلة، أي cold start من scale-to-zero.

مسار المحاكاة. اقرأ infra/deploy.sh وinfra/containerapp.yaml. الشكل الذي ينبغي فهمه هو: ابنِ في السحابة، وانشر مع ingress خارجي وscale-to-zero، وخزّن الأسرار بالاسم. لا تحتاج إلى حساب Azure.

احمل هذا معك

لديك الآن تطبيق Container Apps منشور وعنوانه العام من القرار 3. تعيد القرارات 4 إلى 9 النشر على التطبيق نفسه لإضافة كل واجهة خلفية. احتفظ به؛ لا تشغّل az group delete حتى تنهي المختبر أو تنهي جلسة عمداً.

الخلاصة: الـharness حي على بنية سحابية مُدارة، يمكن الوصول إليه عبر HTTPS، ويتوسع إلى صفر عند الخمول. الهدم أمر واحد az group delete عند الانتهاء. تعطيه القرارات التالية حالة وتخزيناً متينين.

القرار 4: اربط Neon Postgres للحالة المتينة

في سطر واحد: وفّر قاعدة Postgres بلا خادم ووجّه الـharness إليها، حتى تصمد الجلسات والتشغيلات والتتبعات بعد إعادة التشغيل.

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

الصق هذا في وكيل البرمجة. خطط أولاً؛ نفّذ بعد الموافقة.

Wire Neon Postgres as the harness's durable state, following the companion state.py and schema.sql. Create a Neon project at console.neon.com. Apply the five-table schema (sessions, runs, traces, artifacts, audit_log), schema-qualified to public.*. Connect the harness through asyncpg. Two acceptance rules from the companion's normalize_neon_dsn are not optional and prevent silent failures against the pooler:

1. Strip channel_binding from the Neon connection string before handing it to asyncpg; keep sslmode=require. asyncpg does not recognize channel_binding and fails against the pooler if it is left in.
2. Use the pooled endpoint for the running app, and the direct (non-pooled) endpoint for migrations. The pooled endpoint silently drops search_path, which is why every statement is schema-qualified.

Add DATABASE_URL as a local .env value and as an ACA secret, then redeploy. Confirm a run persists across a restart.

ينتهي القرار عندما:

• يبلّغ /health عن "postgres": true بعد إعادة النشر.
• يكتب POST /runs صفاً تستطيع قراءته من جدول runs في Neon.
• تحافظ إعادة تشغيل الحاوية على تاريخ التشغيل، أي الحالة متينة وليست داخل الحاوية.
• لا يحتوي connection string على channel_binding، والهجرات عملت ضد direct endpoint.

مسار المحاكاة. اقرأ state.py وschema.sql. لاحظ شيئين: دالة normalize_neon_dsn التي تزيل channel_binding، وحقيقة أن كل جدول يكتب كـpublic.runs وpublic.sessions وهكذا، لأن pooled endpoint يتجاهل search_path.

احمل هذا معك

لديك الآن مشروع Neon وconnection string من القرار 4: pooled للتطبيق، وdirect للهجرات. يكتب كل من صندوق القرار 6 وقابلية ملاحظة القرار 7 إلى هذه القاعدة. احتفظ بها.

الخلاصة: لدى الـharness ذاكرة. تعيش الجلسات، والتشغيلات، والتتبعات، والآثار، وسجل التدقيق كلها في Neon وتصمد بعد إعادة التشغيل، مع معالجة فخَّي asyncpg. لم يعد الـharness مصاباً بفقدان الذاكرة بين النشرات.

القرار 5: اربط Cloudflare R2 للملفات والآثار

في سطر واحد: وفّر تخزين كائنات وأعط الـharness روابط قصيرة العمر إلى ملفات محددة، حتى تكون مخرجات الوكيل قابلة للتنزيل بلا مشاركة كلمة مرور التخزين.

Cloudflare R2: تخزين كائنات متوافق مع S3 حيث تكون قراءة ملفاتك مجانية. Presigned URL: رابط قصير العمر يسمح لشخص بقراءة ملف محدد أو كتابته من دون حمل كلمة مرور التخزين أبداً. بعد هذا القرار، يمكن حفظ رد الوكيل كملف وإعادته كرابط تنزيل.

الصق هذا في وكيل البرمجة. خطط أولاً؛ نفّذ بعد الموافقة.

Wire Cloudflare R2 as the harness's artifact store, following the companion storage.py. Create an R2 bucket and scoped API credentials. Point a boto3 S3 client at the R2 endpoint https://<account_id>.r2.cloudflarestorage.com with region_name="auto". On a run where save_artifact is true, write the reply to the bucket and return a presigned download URL with a short expiry (one hour). Add the four R2_* values to .env and to ACA secrets, then redeploy.

ينتهي القرار عندما:

• يبلّغ /health عن "r2": true بعد إعادة النشر.
• يعيد POST /runs مع save_artifact true قيمة artifact_url تنزّل الرد.
• يتوقف presigned URL عن العمل بعد انتهاء صلاحيته، فهو محدود وقصير العمر، لا كلمة مرور دائمة.

مسار المحاكاة. اقرأ storage.py. لاحظ التفصيل الوحيد الذي يجعل R2 يعمل مع boto3: وجّه عميل S3 إلى R2 endpoint مع region_name="auto"، وبقية API الخاصة بـS3 بلا تغيير. fallback إلى مجلد محلي هو ما يعمل عند غياب مفاتيح R2.

احمل هذا معك

لديك الآن bucket R2 واعتمادات محدودة من القرار 5. يقرأ صندوق القرار 6 الملفات ويكتبها عبر presigned URLs إلى هذا bucket. احتفظ به.

الخلاصة: يستطيع الـharness تخزين الملفات وإعادتها عبر R2، مع تحديد الوصول بروابط presigned قصيرة العمر بدلاً من مشاركة كلمة مرور التخزين. أصبح الـharness جاهزاً لإعطاء الصندوق الرملي وصولاً إلى الملفات بلا إعطائه المفاتيح.

القرار 6: اربط تنفيذ الصندوق الرملي

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

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

ملاحظة تكلفة قبل البناء. يحتاج مزود الصندوق الرملي الأساسي في الدورة، Cloudflare، إلى خطة Workers مدفوعة وbridge Worker صغير بين Python harness والصندوق الرملي. E2B هو المسار المجاني الواقعي: لديه طبقة Hobby مجانية، وعميل من الدرجة الأولى في الـSDK، ولا يحتاج إلى bridge Worker. يفترض المرافق E2B لهذا السبب بالضبط. استخدم E2B إلا إذا كنت تريد Cloudflare تحديداً.

الصق هذا في وكيل البرمجة. خطط أولاً؛ نفّذ بعد الموافقة.

Wire sandbox execution following the companion sandbox.py and the verified shapes in AGENTS.md. Default to E2B (free tier). Build a SandboxRunConfig only when a sandbox key is set, and attach it through RunConfig, never as a Runner.run kwarg. Two verified shapes from the companion that the older draft got wrong:

1. The E2B path is SandboxRunConfig(client=E2BSandboxClient(), options=E2BSandboxClientOptions(sandbox_type="e2b")). The options object is required and carries the required sandbox_type field; the client constructor takes no options=.
2. If you ever build a Manifest, it is Manifest(entries={...}) with mounts (R2Mount, S3Mount) imported from agents.sandbox.entries. There is no base_image=, mounts=[], or MountSpec. A passed capabilities list replaces the default, so keep Capabilities.default() or concatenate to it.

Add E2B_API_KEY to .env and to ACA secrets, then redeploy. Free-tier path: leave Cloudflare alone, set only E2B_API_KEY, and you need no bridge Worker and no paid plan.

ينتهي القرار عندما:

• يبلّغ /health عن "sandbox": true بعد ضبط مفتاح E2B وإعادة النشر.
• يعيد POST /runs قيمة "used_sandbox": true.
• يستورد الصندوق الرملي من agents.extensions.sandbox.e2b، وما زال الوكيل يجيب عند غياب مفتاح الصندوق الرملي، أي يبقى الـharness مفيداً من دونه.

مسار المحاكاة. اقرأ sandbox.py. لاحظ deferred imports، فالملف يُحمّل حتى بلا sandbox extras، والافتراضي E2B أولاً مع Cloudflare كبديل مدفوع، وأن الدالة تعيد None عند غياب المفتاح، وهذا ما يبقي الـharness عاملاً والصندوق الرملي معطلاً.

احمل هذا معك

رُبط مستوى التنفيذ، القرار 6، فوق الـharness، القرار 1، وبيئته السحابية، القرار 3، وحالته، القرار 4، وتخزينه، القرار 5. أصبح وكيل Maya منشوراً من البداية إلى النهاية على الحزمة ذات المكونات الخمسة. تقويه القرارات 7 إلى 9.

الخلاصة: يعمل تنفيذ الكود الآن في صندوق رملي معزول لا يحمل أسرار الـharness، مرفق عبر RunConfig بالأشكال المتحققة من الـSDK. E2B هو المسار المجاني؛ وCloudflare هو الأساسي المدفوع. اكتملت الحزمة ذات المكونات الخمسة؛ وما تبقى هو جعلها قابلة للملاحظة، ومقاسة، وقابلة للتشغيل.

القرار 7: اربط قابلية الملاحظة

في سطر واحد: اربط واجهات قابلية الملاحظة الأربع واجمعها بـrun_id مشترك، حتى يستطيع الفريق التنقل من أي عرض إلى سببه.

سمى المفهوم 11 أربع واجهات. يربطها هذا القرار ويوفقها. بعده، يستطيع الفريق البدء من Application Insights، أو OpenTelemetry، أو تتبع SDK، أو Phoenix، والوصول إلى أي من الثلاثة الأخرى باتباع معرّف واحد.

الصق هذا في وكيل البرمجة. خطط أولاً؛ نفّذ بعد الموافقة.

Wire the four observability surfaces from Concept 11. Instrument the harness with OpenTelemetry (FastAPI, asyncpg, and HTTP spans) and export to Application Insights. Tag every surface with the same run_id: attach it to the OTel parent span, include it in every structured log line, carry it on the SDK trace, and send it with the Phoenix sample. Stream completed SDK traces to Phoenix as fire-and-forget (if Phoenix is down, log it and continue; Neon is the durable record). Sample at roughly 10% of successful runs and 100% of failed runs, deterministic on run_id so the sampling is stable. Redeploy with the observability keys as ACA secrets.

ينتهي القرار عندما:

• يظهر تتبع OTel لطلب في Application Insights خلال نحو دقيقة.
• يعيد البحث عن run_id واحد في أي واجهة السجل المطابق في الواجهات الأخرى.
• يعرض Phoenix تتبعات حديثة، مع أخذ عينات من كل الفشل وجزء من النجاحات.

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

الخلاصة: رُبطت الواجهات الأربع ووُفقت بـrun_id مشترك، حتى ينتقل الفريق من أي عرض إلى سببه خلال دقائق. هذه قابلية ملاحظة إنتاجية لـagent harness: ليست checklist، بل معمارية.

القرار 8: اربط حزمة التقييمات

في سطر واحد: صِل الأطر الأربعة من دورة التطوير المدفوع بالتقييمات بتتبعات الـharness، منتجاً بوابة انحدار في CI، وتقرير سلوك ليلياً، وطقساً أسبوعياً لترقية التتبعات إلى تقييمات.

ثبّت المفهوم 12 الحد: تتبعات في Neon وPhoenix. يربط هذا القرار أطر التقييم الأربعة بهاتين الواجهتين. هنا يُعلّم الربط الكامل للتقييمات؛ إذا لم تكن قد بنيت حزمة التقييمات نفسها، فأنجز دورة التطوير المدفوع بالتقييمات أولاً، لأن هذا القرار يرفق تلك الحزمة بالنشر.

الصق هذا في وكيل البرمجة. خطط أولاً؛ نفّذ بعد الموافقة.

Wire the four eval frameworks from the Eval-Driven Development course to the deployed harness's traces. Attach each at its point:

1. DeepEval as the CI regression gate. On every pull request that touches the agent or prompts, run DeepEval against the committed golden dataset by hitting a staging POST /runs, and block the merge if a previously passing case now fails.
2. A nightly scheduled job (Container Apps Jobs) that reads the prior 24 hours of traces from Neon, grades them with OpenAI Agent Evals against the team's rubric, runs Ragas on the traces that used retrieval, writes a report to the repo, and posts the summary to Slack.
3. Phoenix inline evaluators that run as traces arrive (hallucination, policy, tool-correctness), tagging scores without blocking runs.
4. A weekly ritual, documented in a runbook: review Phoenix's flagged traces and promote the eval-worthy ones into the golden dataset, so each becomes a future regression test.

ينتهي القرار عندما:

• يمنع DeepEval gate pull request يتعمد إضعاف السلوك.
• تنتج الوظيفة الليلية تقرير سلوك في المستودع وتنشره إلى Slack.
• يعرض Phoenix درجات inline evaluator على تتبعات حديثة، ويُوثق طقس الترقية ويُشغل مرة من البداية إلى النهاية.

مسار المحاكاة. اقرأ إعدادات خط التقييم وCI workflows في المرافق. الشكل المطلوب ترسيخه هو المخرجات التشغيلية الثلاثة: بوابة قبل الدمج تلتقط الانحدارات، وتقرير ليلي يلتقط الانجراف، وطابور ترقية يحول فشل الإنتاج إلى اختبارات جديدة.

الخلاصة: اتصلت حزمة التقييمات بالـharness المنشور عبر التتبعات. ينتج التكامل ثلاثة مخرجات تشغيلية: بوابة انحدار في CI، وتقرير سلوك ليلي، وطابور ترقية أسبوعي. ينمو انضباط التقييمات الآن من حركة الإنتاج الحقيقية بدلاً من خيال الفريق.

القرار 9: قائمة الإنتاج

في سطر واحد: أكمل الانضباط التشغيلي: تدوير الأسرار، والنشر الأزرق/الأخضر، ودفتر تشغيل للمناوبة، والنسخ الاحتياطي والاسترداد، وحدود المعدل.

بعد أن أصبح الـharness قابلاً للملاحظة، القرار 7، ومقاساً، القرار 8، يضيف هذا القرار ما تحتاجه لتركه عاملاً من دون قلق. الأزرق/الأخضر: اشحن نسخة جديدة بلا توقف بتشغيلها بجانب القديمة ثم تحويل المرور إليها.

الصق هذا في وكيل البرمجة. خطط أولاً؛ نفّذ بعد الموافقة.

Complete the production discipline for the harness, documented in a runbook. Cover:

1. Secrets rotation: a procedure to add a new credential beside the old one, redeploy, verify, then revoke the old.
2. Blue/green deploys: a script that creates a new revision at 0% traffic, checks /health on it, shifts 10% and watches Application Insights, then shifts to 100% and keeps the old revision for a day for rollback.
3. An on-call runbook with five scenarios (high error rate, high latency, sandbox provider down, Neon unreachable, R2 unreachable), each with investigation and remediation steps.
4. Backup and recovery: Neon point-in-time recovery, R2 versioning, and ACA revision rollback.
5. Per-user rate limits at the middleware layer, returning 429 with Retry-After when exceeded.
6. Cost alerts that fire when daily spend jumps well above the recent average.

ينتهي القرار عندما:

• توجد لكل الأسرار عملية تدوير موثقة ومختبرة.
• يعمل نشر أزرق/أخضر واحد من البداية إلى النهاية: مراجعة جديدة مفحوصة، مرور محوّل، ومراجعة قديمة محفوظة للرجوع.
• تعمل حدود المعدل، أي يعيد الطلب بعد الحد 429، وتكون تنبيهات التكلفة مضبوطة.

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

الخلاصة: أصبح الـharness جاهزاً للإنتاج بالمعنى الكامل: قابل للملاحظة، ومقاس، وقابل للتشغيل. تتدوّر الأسرار، والنشرات أزرق/أخضر، ودفتر التشغيل يغطي أنماط الفشل، والنسخ الاحتياطية مختبرة، وحدود المعدل تحد blast radius لأي قفزة. تستطيع تركه عاملاً والاستجابة بثقة عندما ينكسر شيء.

---

الجزء 6: الحدود الصادقة

ينتج المختبر نشراً عاملاً. يسمي الجزء 6 ما لا يحله، وأين يكلف أكثر من المتوقع، وأين حدوده. أربعة مفاهيم وخمسة أنماط يجب تجنبها.

المفهوم 13: اقتصاديات تكلفة cloud agent harness

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

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

الطبقة	نصيبها من الفاتورة
Model API (OpenAI)	90 إلى 98% على كل مقياس
تنفيذ الصندوق الرملي	أكبر الباقي عند الحجم العالي
حوسبة الـharness (ACA)	صغيرة؛ يبقيها scale-to-zero قريبة من الصفر عند الخمول
الحالة المتينة (Neon)	صغيرة؛ تغطي الطبقة المجانية الاستخدام الخفيف
تخزين الملفات (R2)	صغير؛ والخروج مجاني

تعامل مع الأرقام كمديات تقريبية لا أسعار دقيقة. على مقياس صغير، نحو 100 تشغيل يومياً، تكون الفاتورة كلها في حدود مئة وبضعة دولارات شهرياً، وتكون API النموذج نحو تسعة أعشارها. على مقياس متوسط، نحو 10,000 تشغيل يومياً، تكون الفاتورة في أوائل عشرات الآلاف شهرياً، وتكون API النموذج نحو 98% منها. على مقياس كبير، نحو مليون تشغيل يومياً، تدخل الفاتورة في سبعة أرقام شهرياً، ومعظمها تقريباً API النموذج. تنمو طبقات البنية التحتية أيضاً، لكنها تبقى تحت 5% من الإجمالي طوال الوقت.

تتبع الخلاصات الصادقة من ذلك مباشرة. البنية التحتية السحابية تكاد تكون دائماً تحت 5% من الفاتورة، لذلك ذراع التكلفة الأعلى أثراً هو النموذج لا البنية التحتية: استخدم نموذجاً أرخص للقرارات البسيطة، وخزّن التعليمات المؤقتة حيث يدعم الـSDK ذلك، واجعل system prompts قصيرة. تكلفة البنية التحتية متوقعة وخطية تقريباً مع الحركة؛ لا تأتي منها فواتير مفاجئة. يهم خروج R2 المجاني أكثر في الأحمال كثيفة الملفات، ولا يكاد يظهر في الأحمال النصية مثل Maya. تتوسع تكلفة الصندوق الرملي مع وقت التنفيذ النشط، لذلك تكلف الوكلاء كثيفة الحوسبة هناك أكثر، بينما تبقى الوكلاء التي تنتظر النموذج غالباً رخيصة.

الخلاصة: لهذه الوصفة اقتصاديات متوقعة. تكلف البنية التحتية السحابية من عشرات إلى بضعة آلاف من الدولارات شهرياً حسب الحركة؛ وتشكل API النموذج 90 إلى 98% من إجمالي الإنفاق على كل مقياس. الوصفة رخيصة على مستوى البنية التحتية، لذلك حسّن النموذج لا البنية. تعامل مع كل رقم هنا كمدى رتبة حجم، لا عرض سعر.

المفهوم 14: اعتبارات تعدد المناطق

تنشر هذه الوصفة في منطقة واحدة عمداً. active-active متعدد المناطق مشكلة أصعب بكثير، ومعظم النشرات لا تحتاج إليه. تحتاج إليه لواحد من ثلاثة أسباب: الكمون، عندما ينتشر المستخدمون عالمياً وتضيف منطقة واحدة round-trip محسوساً؛ أو التوفر، عندما يكون التزام uptime عندك 99.99% أو أعلى وتكون منطقة واحدة غير مقبولة؛ أو الامتثال، عندما تتطلب قواعد توطين البيانات بقاء بيانات المستخدم في منطقة محددة.

تختلف المكونات في صعوبة تعدد المناطق. R2 والصندوق الرملي عالميان أصلاً على شبكة Cloudflare، لذلك لا يحتاجان إلى عمل إضافي. ACA منطقة واحدة لكل environment، لذلك يعني تعدد المناطق environments كثيرة خلف load balancer عالمي. يدعم Neon read replicas في مناطق أخرى، لكن الكتابات تظل إلى primary، لذلك تحتاج حالة الوكيل كثيفة الكتابة إلى تصميم قاعدة بيانات أعقد. الوصفة الصادقة هي environments أكثر، وread replicas، وfront door عالمي، مع ارتفاع التكلفة التشغيلية في كل منطقة. إذا كان معظم مستخدميك في منطقة واحدة، وهدف uptime هو 99.9%، وتفي منطقة واحدة بقواعد بياناتك، فالإجابة الصحيحة هي منطقة واحدة؛ لا تدفع ثمن تعقيد لا تحتاج إليه.

الخلاصة: المنطقة الواحدة هي الافتراضي والقرار الصحيح لمعظم النشرات. تعدد المناطق حقيقي لحاجة الكمون العالمي أو التوفر العالي أو توطين البيانات، والمسار هو front door عالمي مع ACA متعدد المناطق وNeon read replicas. R2 والصندوق الرملي عالميان بالفعل. active-active أعمق موضوع مستقبلي مستقل؛ تجنبه إن استطعت.

المفهوم 15: متى تهاجر خارج الوصفة

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

المحفزات: تزامن عالٍ مستمر فوق نحو 25 replica من ACA، حيث تفضل الاقتصاديات وحسابات الاتصال نقل الـharness إلى Kubernetes، مع بقاء كود التطبيق كما هو. active-active متعدد المناطق، بحسب المفهوم 14. حوسبة متخصصة مثل GPU، حيث يناسب مزود صندوق رملي أصيل في GPU وتنتقل Manifest المحمولة معك. قاعدة امتثال تشترط تشغيل الصندوق الرملي داخل سحابتك، فتستبعد SaaS sandbox وتدفعك إلى bring-your-own provider. وتجاوز Postgres كمخزن أساسي عند أحجام كتابة عالية جداً، ما يشير إلى SQL موزع أو تخزين مقسم، وهو التغيير الأكثر توغلاً بين الخمسة.

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

المفهوم 16: ما الذي لا يحله النشر

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

لا ينتج شهادة امتثال. تحصل على الضوابط التقنية التي يتوقعها إطار مثل SOC2، لكن الشهادة تحتاج إلى تدقيق طرف ثالث وأشهر من الأدلة؛ خطط لها كمسار عمل منفصل. لا يعطيك برنامج استجابة للحوادث. يغطي دفتر التشغيل الإصلاح التقني، لا من يُستدعى، وكيف تُعلن الحوادث، وكيف تدار post-mortems؛ طبقة الناس والعملية هذه عليك بناؤها. لا يحسم المسؤولية القانونية عن أفعال الوكيل. يسجل audit log ما حدث، لكن الإطار القانوني حول قرارات الوكلاء ما زال يتشكل. لا يوقف prompt injection على مستوى السلوك. يحفظ فصل الـharness عن الصندوق الرملي الكود المحقون بعيداً عن أسرارك، لكنه لا يمنع رسالة مصممة من توجيه رد الوكيل؛ يحتاج ذلك إلى حواجز أمان، وفحوص إدخال، وred-teaming، وكثير منه عمل حزمة التقييمات. لا يتعامل مع ترقيات النماذج نيابة عنك؛ حزمة التقييمات هي انضباط اختبار نموذج جديد قبل التحويل. ولا يمنع انفلات التكلفة؛ تلتقط المراقبة قفزة خلال ساعات، لكن السقوف اليومية ومفاتيح القتل دفاعات إضافية تضيفها فوق ذلك.

الخلاصة: يعلّم النشر substrate الذي يجعل هذه الهموم قابلة للمعالجة، لا الهموم نفسها. تبقى شهادة الامتثال، وعملية الاستجابة للحوادث، والمسؤولية القانونية، وprompt injection على مستوى السلوك، وترقيات النماذج، وانفلات التكلفة، أعمالاً حقيقية بعد المختبر. لا يتغير العمود المعماري عندما تضيفها؛ بل يتغير الانضباط التشغيلي حوله.

خمسة أشياء لا تفعلها

تتجنب الوصفة خمسة أنماط سوء. تسميتها تساعد الفريق على تجنب الرجوع إليها بعد أن يشحن النشر.

1. لا تشغّل الكود الذي يولده الوكيل داخل الـharness. استدعاء مثل exec(model_output) في عملية الـharness أسوأ من SQL injection، لأن سطح الهجوم هو استدلال النموذج كله. حد الصندوق الرملي غير قابل للتفاوض؛ يحمل الـharness المفاتيح، ولا يحق لكود الوكيل لمسها.
2. لا تضع الاعتمادات الجذرية في Manifest. كل ما في Manifest يعبر إلى الصندوق الرملي. لا يعبر الحد إلا presigned URLs وtokens قصيرة العمر؛ تبقى database strings وAPI keys في الـharness.
3. لا تتجاوز scale-to-zero في التطوير. تطبيق تطوير يبقى دافئاً على مدار الساعة، مضروباً في عدد الناس والخدمات، يكلف بهدوء مئات شهرياً على حوسبة خاملة معظم الوقت. اقبل cold start في التطوير.
4. لا تنشر بلا ربط حزمة التقييمات. تجاوزها هو أغلى اختصار في نشر الوكلاء: تشحن تغييرات تنجح في مراجعة الكود، وتكسر السلوك، وتظهر كشكاوى بعد أسابيع. بوابة التقييمات هي الفرق بين نشر وكلاء ونشر وكلاء يبقون جيدين.
5. لا تشغّل الـharness بلا rate limiting. النشرات في اليوم الأول بلا حدود هي طريقة اكتشاف الفرق، بعد ذكر واحد ينتشر، أنها دفعت ثروة لمزود نموذج في يوم واحد. الحدود السخية مقبولة؛ لا حدود هو الإعداد الخطر.

---

الجزء 7: الخاتمة

المفهوم 17: الـharness المنشور كتجسيد

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

تستند الدورة كلها إلى فكرة واحدة: الـharness هو مستوى التحكم والصندوق الرملي هو مستوى التنفيذ، وهذا الفصل الواحد هو ما يجعل النشر آمناً ومتيناً وقابلاً للتوسع. كل ما ربطته في المختبر يخدمه. يحتفظ الـharness بالمفاتيح، والحالة، والتنسيق؛ ويشغّل الصندوق الرملي الكود الخطر بلا أي مفاتيح؛ وتحدد presigned URLs وصول الملفات عبر الحد؛ وتعرض قابلية الملاحظة ما يحدث؛ وتخبرك حزمة التقييمات هل ما زال صحيحاً. الخروج عن الوصفة مقبول. الخروج عن المعمارية ليس مقبولاً. شغّل الـharness والصندوق الرملي في مستويين منفصلين، ولاحظ عبر الواجهات الأربع، وقِس السلوك ضد حزمة تقييمات تنمو من الإنتاج، وستعمل المعمارية أياً كانت المكونات السحابية التي تختارها.

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

الخلاصة: تحقق هذه الدورة المعمارية كخدمة سحابية منشورة إنتاجياً مع قابلية ملاحظة وحزمة تقييمات موصولة تشغيلياً. تنتج الوصفة، FastAPI على Azure Container Apps وNeon وR2 وصندوق رملي لتنفيذ الكود وOpenTelemetry مع Application Insights وPhoenix وحزمة التقييمات في CI، harness بفصل بين مستوى التحكم ومستوى التنفيذ، وحالة متينة، ووصول ملفات محدود، وقابلية ملاحظة بأربع واجهات، وقياس سلوك مستمر. بنى مسار التصنيع الشركة؛ وهذه الدورة تنشرها.

جرّب مع AI. افتح وكيل البرمجة. الصق:

"I've completed the manufacturing track through this deployment course. List the three things I learned that I'll apply most often in the next year of building agents, and the three I'll apply rarely but that will be critical when I do. Explain each briefly. Then, for the composition this course wired (the Eval-Driven Development course's eval suite attached to a deployed harness), name what you expect to be the hardest part of operating it in practice: which discipline will be tempting to skip when the team is under deployment pressure?"

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

---

نسخة ورشة اليوم الواحد

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

الوقت المتاح	أبقِ	احذف
8 ساعات، مكثف يوم واحد	تمهيد الحزمة، Docker وFastAPI فقط · المفاهيم 1 إلى 3، العمود المعماري · القرارات 0 إلى 5، من المسبار إلى R2 · المفهوم 13، التكلفة · خاتمة الجزء 7	تمهيد Neon وR2، اقرأه وحدك · المفاهيم 4 إلى 12، استخدمها كمرجع · القرار 6، الصندوق الرملي كعرض لا بناء · القرارات 7 إلى 9 مؤجلة · المفاهيم 14 إلى 16 مؤجلة
يومان	أضف القرارين 6 و7، الصندوق الرملي وقابلية الملاحظة · المفاهيم 8 إلى 11	القراران 8 و9 مؤجلان · المفاهيم 12 و14 إلى 16 مؤجلة
3 إلى 4 أيام	أضف القرار 8، حزمة التقييمات · المفهوم 12	القرار 9 مؤجل · المفاهيم 14 إلى 16 مؤجلة
أسبوع كامل، 5 إلى 7 أيام	كل شيء: المسار المتقدم كاملاً	لا شيء

للورش القصيرة، أبقِ العمود المعماري، أي فصل الـharness عن الصندوق الرملي والحزمة ذات المكونات الخمسة، ومسار النشر الأدنى، القرارات 0 إلى 5. يمكن جعل التقوية والحدود الصادقة دراسة ذاتية بعد ذلك. الفهم المعماري هو ما يجب أن يغادر به الطلاب؛ وعمق التنفيذ هو ما ينمون إليه.

---

بطاقة مختصرة

#	المفهوم	الخلاصة الأساسية
1	"يعمل على جهازي" ليس نشراً	الإنتاج يعني إعادة معمرة الوكيل إلى harness، مستوى تحكم، وصندوق رملي، مستوى تنفيذ، لا تغليف سكربت حاسوب
2	فصل الـharness عن الصندوق الرملي	العمود الفقري: ينسق الـharness بالأسرار والحالة؛ وينفذ الصندوق الرملي الكود؛ والحد شبكي وأمني
3	ما يحتاجه الـSDK من البنية	خمس واجهات، خدمة HTTP، وحالة متينة، وتخزين ملفات، وتنفيذ معزول، وتنسيق، وكل واحدة مربوطة بمكوّن
4	FastAPI كطبقة ويب للـharness	أصيل في عدم التزامن لمطابقة الـSDK، ومخططات API تلقائية، ونماذج Pydantic
5	Azure Container Apps كبيئة تشغيل	Ingress، وتوسع تلقائي مع scale-to-zero، وأسرار، ومراجعات كبدائيات مُدارة
6	Neon Postgres للحالة المتينة	Postgres للحالة العلائقية؛ وNeon للتوسع بلا خادم والتفريع الرخيص
7	Cloudflare R2 للملفات	خروج مجاني، ومتوافق مع S3، وpresigned URLs تحد الوصول بملف واحد في كل مرة
8	قدرات تنفيذ الصندوق الرملي	نظام ملفات، وshell، وتثبيت حزم، وتخزين مركب، وكلها معزولة وزائلة
9	اختيار مزود الصندوق الرملي	E2B هو المسار المجاني؛ Cloudflare هو الأساسي المدفوع؛ والآخرون يناسبون حاجات محددة
10	التسليم من الـharness إلى الصندوق الرملي	يعلن Manifest مساحة العمل؛ وتحدد presigned URLs الملفات؛ ولا تعبر الاعتمادات الجذرية أبداً
11	قابلية الملاحظة كواجهة	أربع واجهات، Application Insights وOpenTelemetry وتتبع SDK وPhoenix، يربطها run_id مشترك
12	التقييمات كواجهة	تمر عبر التتبعات في Neon، المتين، وPhoenix، الفوري؛ وتتصل أطر التقييم في نقاط محددة
13	اقتصاديات التكلفة	البنية التحتية تحت 5% من الفاتورة؛ API النموذج 90 إلى 98%؛ حسّن النموذج لا البنية
14	تعدد المناطق	منطقة واحدة افتراضياً؛ تعدد المناطق فقط للكمون العالمي أو uptime 99.99%+ أو توطين البيانات
15	متى تهاجر خارج الوصفة	تزامن ثقيل، أو تعدد مناطق، أو GPU، أو امتثال صندوق داخل السحابة، أو حجم كتابة متطرف
16	ما لا يحله النشر	شهادة الامتثال، وعملية الحوادث، والمسؤولية القانونية، وprompt injection السلوكي، وترقيات النماذج، وانفلات التكلفة
17	الـharness المنشور كتجسيد	هذه الدورة تشحن ما بناه مسار التصنيع، مع قابلية ملاحظة وحزمة تقييمات موصولة تشغيلياً

#	القرار	الناتج
0	افحص الـSDK	طباعة النسخة المثبتة، وتوفيق الملف مع الوثائق الحية، وملاحظة "What changed"
1	هيكل الـharness	تطبيق FastAPI، ووكيل، وحالة وتخزين اختياريان، يعمل على OPENAI_API_KEY وحده
2	حوّل إلى حاوية	صورة صغيرة قابلة للتكرار تعمل محلياً وفي السحابة
3	انشر إلى Azure Container Apps	عنوان HTTPS عام، وscale-to-zero، وأسرار محفوظة بالاسم
4	اربط Neon Postgres	مخطط خمسة جداول، pooled للتطبيق وdirect للهجرات، وإزالة channel_binding
5	اربط Cloudflare R2	Bucket، واعتمادات محدودة، وpresigned download URLs قصيرة العمر
6	اربط تنفيذ الصندوق الرملي	عميل E2B مجاني مرفق عبر RunConfig؛ وCloudflare كبديل مدفوع
7	اربط قابلية الملاحظة	أربع واجهات يربطها run_id مشترك؛ وعينة Phoenix fire-and-forget
8	اربط حزمة التقييمات	بوابة CI للانحدار، وتقرير سلوك ليلي، وترقية أسبوعية من trace إلى eval
9	قائمة الإنتاج	تدوير أسرار، ونشر أزرق/أخضر، ودفتر مناوبة، ونسخ احتياطي واسترداد، وحدود معدل

مرجع سريع: أوامر النشر

# Local dev (Beginner track)
uv sync                                         # install from the lockfile
uv run uvicorn maya_harness.main:app --reload   # boot the harness locally
# Pin: openai-agents>=0.17,<0.18

# Cloud deployment (Intermediate / Advanced): Azure Container Apps
az group create --name maya-rg --location eastus
az acr create --resource-group maya-rg --name <acr-name> --sku Basic --admin-enabled true
az acr build --registry <acr-name> --image maya-harness:latest .   # build in the cloud
az containerapp env create --name maya-env --resource-group maya-rg --location eastus
az containerapp create --name maya-harness --resource-group maya-rg \
  --environment maya-env --image <acr-name>.azurecr.io/maya-harness:latest \
  --target-port 8000 --ingress external --min-replicas 0 --max-replicas 3 \
  --secrets "openai-api-key=$OPENAI_API_KEY" \
  --env-vars "OPENAI_API_KEY=secretref:openai-api-key"

# Tear-down (cost discipline)
az group delete --name maya-rg --yes

# Neon Postgres (console.neon.com)
# Strip channel_binding from the connection string before asyncpg; keep sslmode=require.
# Use the pooled endpoint for the app; the direct (non-pooled) endpoint for migrations.
psql "$DIRECT_BRANCH_URL" -f schema.sql          # migrations on the direct endpoint

التنزيل المرافق

يحمل ملف zip المرافق الـharness المشغّل، وAGENTS.md، أي التوجيه، وقواعد المشروع، والمعمارية، ومسبار SDK، والكود المتحقق لكل واجهة خلفية، وDockerfile، وأشكال نشر Azure، وschema.sql: deploying-agents-crash-course.zip.

المراجع

الروابط محدثة حتى مايو 2026؛ تحقق منها قبل الاستشهاد بها في عملك.

مسار agent-factory:

• حلقة الوكيل والـSDK: بناء وكلاء الذكاء الاصطناعي.
• حزمة التقييمات التي تربطها هذه الدورة بالـharness: التطوير المدفوع بالتقييمات.
• الغلاف التشغيلي، أي التنفيذ المتين والواجهة الخامسة لقابلية الملاحظة: عامل إنتاج بجهاز عصبي.
• انضباط التصميم الذي يسبق البناء: اختيار معماريات الأنظمة الوكيلة.
• الأطروحة وراء المسار: /docs/thesis.

الحزمة ذات المكونات الخمسة:

• OpenAI Agents SDK (Python): الحزمة openai-agents>=0.17,<0.18؛ الوثائق في https://openai.github.io/openai-agents-python؛ ومرجع Manifest ومزودي الصندوق الرملي في المصدر نفسه. شُحن فصل الـharness عن الصندوق الرملي كجزء مدمج من الـSDK في إصدار 15 أبريل 2026: https://openai.com/index/the-next-evolution-of-the-agents-sdk/.
• FastAPI: معالجة طلبات غير متزامنة ومخططات API مولدة تلقائياً. https://fastapi.tiangolo.com
• Azure Container Apps: ingress، وتوسع تلقائي، وأسرار، ومراجعات. https://learn.microsoft.com/en-us/azure/container-apps/
• Neon Postgres: Postgres بلا خادم مع تفريع؛ وpooled endpoint وفخ channel_binding هما تفصيلان أساسيان في القرار 4. https://neon.com
• Cloudflare R2: تخزين متوافق مع S3 بخروج مجاني؛ يدعم الـSDK R2 كتركيب Manifest. https://developers.cloudflare.com/r2/
• Code-execution sandbox: E2B (https://e2b.dev، طبقة Hobby مجانية، وعميل SDK أصيل) هو المسار المجاني؛ وCloudflare Sandbox، جزء من منصة Workers، هو الأساسي المدفوع. تناسب Modal وDaytona حاجات GPU والحاجات داخل سحابتك.

مراجع التشغيل والأمن:

• OpenTelemetry: معيار التتبع الذي يصدّره الـharness. https://opentelemetry.io
• OWASP API Security Top 10: checklist الأمن الذي يغطيه القرار 9 بدرجة كبيرة. https://owasp.org/API-Security/editions/2023/en/0x11-t10/

---

الدورة 14 من مسار البدء: دورة النشر المكثفة من البداية إلى النهاية لمسار agent-factory. Harness، وصندوق رملي، وقابلية ملاحظة، وحزمة تقييمات مركبة، مع تمهيد للحزمة للقراء الجدد على Docker وFastAPI وNeon وR2.