الاستعداد لـ Production

إذا بدأت بـ Config مولّدة من OpenAPI، فراجع العمليات المتاحة والمصادقة وConfirmation previews والتحقق من الاستجابات وعنوان البيئة قبل الإطلاق. عند تغيير API، ولّد ملفًا مرشحًا منفصلًا وقارنه وادمج الإعدادات المراجعة بدل استبدال Config المنشورة.

اجعل الجاهزية لـ Production مبنية على دليل

بعد ربط أول Endpoint، جرّب مسارات تطبيقك على بيئة Staging للـ API الفعلية. سجّل الطلب والاستجابة وحالات المتابعة وأخطاء الصلاحية المتوقعة. استخدم تمرين الحجز إذا احتجت إلى اختبار مستقل لسياسات Selection والـ Confirmation؛ ليس خطوة إلزامية لكل تطبيق. نجاح التحقق من الإعداد وحده لا يثبت سلوك Production.

يمكن لتطبيق صغير بعملية واحدة استخدام مخازن الذاكرة إذا كان فقد الـ Sessions المعلّقة عند إعادة التشغيل مقبولًا. أما workers المتعددة فتحتاج State مشتركة وتنفيذ المعاملات بالتتابع وخطة واضحة لمشاركة بيانات الاعتماد. هذه تكاملات في التطبيق، وليست مفاتيح YAML.

اختبر الحجز في Staging قبل الإطلاق

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

احتفظ بإصدار الحزمة مع نسخة الـ Config التي راجعتها. تغيّر Config يبطل الـ Sessions القديمة المعلّقة؛ جهّز تجربة المستخدم لمن كانت قائمة اختياراته مفتوحة أثناء النشر. راقب Confirmations القديمة والتنفيذ غير المحسوم ورفض API وجودة Routing بعد الإطلاق.

يجب أن يستند كل بند أدناه إلى اختبار أو تنفيذ أو إجراء تشغيلي. وضع علامة اكتمال دون دليل لا يغيّر سلوك Runtime.

استخدم هذه الصفحة كشرط لاعتماد الإصدار.

الإعدادات

• الإعداد ثابت طوال عمر instance من Runtime.
• لكل Tool وصف محدد وinput Schema صريحة.
• Mappings الطلب صريحة ولا تحتاج إلى استنتاجات خفية.
• توجد Output Schemas لعقود API المهمة.
• تغطي private_fields أسرار التنفيذ التي تعيدها APIs.
• تستخدم فهارس الـ Tools الكبيرة retriever انتقائيًا أو حدودًا آمنة لـ Semantic Recall.

Auth

• يدير التطبيق المضيف sessionId ويربطه بالمتصل الذي جرت مصادقته.
• تُمرّر user Tokens عبر auth.token فقط.
• تتحقق API المستقبِلة من الصلاحية لكل مورد محمي.
• تُحفظ بيانات اعتماد API والخدمات في البيئة أو نظام إدارة البيانات الحساسة.
• تستخدم REST Endpoints في Production التي تحمل بيانات اعتماد HTTPS.
• يؤدي تبديل الحساب إلى مسح Sessions AGENTO أو استبدالها.

العمليات ذات الأثر

• كل عملية كتابة مصنّفة كـside-effect أو destructive.
• كل كتابة تتطلب Confirmation.
• تتضمن معاينة Confirmation حقائق يفهمها المستخدم.
• يدعم backend خاصية idempotency للكتابات المهمة.
• يوجد إجراء للتحقق لدى الـ API من نتيجة العملية عندما لا يكون نجاح التنفيذ أو فشله معلومًا.
• للعمليات المدمّرة تجربة استخدام أكثر وضوحًا وسجل تدقيق.

النشر الأفقي

• تضمن SessionStore.transact() تسلسل الـ Session الواحدة عبر workers باستخدام distributed locking وfencing أو ما يكافئهما.
• مخزن الـ Sessions مشترك.
• مخزن Tokens مشترك إذا كان الاستكمال قد يصل إلى worker أخرى.
• تشترك workers في مفتاح تشفير بيانات الاعتماد عند استخدام مخزن Tokens مشترك.
• محدّد المعدل مشترك عندما تكون الحدود العامة مهمة.
• يُفهم أن circuit breakers تخص كل instance، وليست عامة.

الشبكة

• تمنع قواعد خروج الشبكة في التطبيق والبنية التحتية الإعداد غير الموثوق من تحويل AGENTO إلى عميل شبكي بلا قيود.
• المهل الزمنية مناسبة لكل REST Endpoint.
• حدود حجم الـ Response واقعية.
• عدد محاولات Retry محدود بما يناسب العملية.
• تُعاد العمليات الآمنة أو idempotent فقط.

AI Models

• اختُبرت IDs الخاصة بالـ Providers والـ AI Models التي سيستخدمها التطبيق.
• تغطي حالات تقييم Routing لغة المستخدم الحقيقية والطلبات الملتبسة.
• اختُبرت الطلبات العربية ومتعددة اللغات إذا كان المنتج يدعمها.
• يوجد مسار بديل في التطبيق أو للمستخدم عند فشل الـ AI Model.
• صياغة AI ليست المصدر الوحيد لحقول الواجهة الموثوقة.

المراقبة

• يتوفر requestId وsessionId في السجلات الموثوقة.
• تُصدّر مقاييس Runtime.
• تُجمع hooks دون إضافة أسرار.
• توجد لوحات لرموز أخطاء Auth والخدمات والاختيارات القديمة والتنفيذ غير المحسوم.
• يمكن فحص حالة circuit breaker.

الاختبارات

• نجاح المسارات الطبيعية للقراءة فقط.
• الـ Input الناقصة.
• الخيارات الفارغة.
• تعدد الخيارات.
• انتهاء صلاحية Selection.
• انتهاء صلاحية Confirmation.
• Responses 401 و403.
• التعافي من 409 و410 عند تفعيله.
• سلوك 429 و5xx وانتهاء المهلة.
• مخالفة Output Schema.
• إلغاء الطلب.
• إبطال الـ Session القديمة عند تغيّر الإعداد.
• إجراء التعامل مع تعطل worker أو التنفيذ غير المحسوم.

التحقق من الإصدار

الإصدار العام الموثق هو agento-runtime@1.0.0. قبل ضمان ملاءمته لـ Production، ثبّت commit أو tag خضع للمراجعة، وشغّل اختبارات المستودع، وأضف اختبارات تكامل مع APIs لديك، وحدّد المسؤولية التشغيلية عن الآثار غير المحسومة وقفل الـ Sessions الموزّع.