النمط
فتحت إحدى الأسواق الكبرى أدوات البائعين لوكلاء خارجيين، بدءاً بمزوّد نموذج واحد. وتتبعها منصات الحجوزات والتجارة والضرائب بأسطح موجهة للوكلاء خاصة بها. هذا صنف جديد من الواجهات: المستهلك الأساسي هو مخطط (planner)، وليس شخصاً يستخدم متصفحاً. والفرق ليس شكلياً. يستطيع الإنسان أن يستنتج الشروط المسبقة الناقصة من السياق، ويتحمّل الأخطاء الغامضة، ويعيد المحاولة يدوياً عند فشل إجراء. أما المخطط فلا يستطيع. إنه يحتاج إلى عقد صريح وحتمي وقابل للقراءة آلياً.
ما يحتاجه المتصلون الآليون وتغفله واجهات API الموجهة للبشر
صُممت معظم واجهات API العامة لمطورين يكتبون شيفرة تستهدفها، لكن المستهلك وقت التشغيل يبقى إنساناً يقرأ التوثيق ويفحص الاستجابات ويكتب منطقاً دفاعياً. أما المتصلون من الوكلاء فيزيلون هذا الإنسان من الحلقة. وهم يحتاجون إلى ثلاثة أمور غالباً ما تكون غائبة.
شروط مسبقة قابلة للقراءة آلياً
يجب بيان الحقول المطلوبة لكل انتقال حالة على شكل schema، لا على شكل نص نثري. مثلاً، قد تتطلب نقطة نهاية حجز حقل guest_count فقط عندما تكون status هي confirmed، أو حقل tax_id فقط لحجوزات الأعمال. وإذا كان هذا مدفوناً في فقرة، فسيخمّن المخطط. انشر آلة حالة مع الحقول المطلوبة لكل انتقال والقيم المسموح بها والآثار الجانبية. إن JSON Schema أو أي وصف رسمي مكافئ ليس اختيارياً؛ إنه الواجهة نفسها.
تصنيف حتمي للأخطاء
يجب تصنيف الأخطاء حسب الرمز (code)، لا حسب الرسالة. يحتاج المخطط إلى التمييز بين:
- قابل لإعادة المحاولة: فشل شبكي عابر، حد معدل، تنازع على قفل. يستطيع الوكيل التراجع وإعادة المحاولة.
- نهائي: مدخل غير صالح، صلاحية مفقودة، انتقال حالة غير مدعوم. إعادة المحاولة لن تفيد.
- يحتاج إلى إنسان: قاعدة عمل غامضة، مراجعة يدوية مطلوبة، نزاع. ينبغي للوكيل التصعيد.
إذا كانت الإشارة الوحيدة رسالة نصية حرة، فعلى المخطط إما أن يثبّت مطابقة نصية هشة أو أن يستسلم. وكلاهما فشل. انشر مجموعة رموز أخطاء مستقرة مع تعيين موثّق لهذه الأصناف الثلاثة، وأدرج الصنف في جسم الاستجابة بحيث يمكن تحليله دون جدول بحث.
مفاتيح idempotency في كل نداء مُعدِّل
قد يعيد المخطط محاولة خطوة بعد مهلة أو انهيار أو فشل جزئي. وبدون مفتاح idempotency، قد تؤدي إعادة محاولة POST /bookings إلى حجز مزدوج أو خصم مزدوج. يجب أن يكون المفتاح مولّداً من العميل، وفريداً لكل عملية منطقية، ومحترماً من الخادم خلال نافذة محددة. وينبغي للخادم أن يعيد الاستجابة نفسها لمفتاح مكرر، لا مورداً جديداً. هذه ليست فكرة جديدة، لكنها تُطبَّق بشكل غير متسق. وبالنسبة للأسطح الموجهة للوكلاء، فهي إلزامية في كل نداء مُعدِّل، بما في ذلك الإلغاءات والمبالغ المستردة.
الحصص كجزء من العقد
غالباً ما تكون حدود المعدل فكرة تشغيلية لاحقة. أما بالنسبة للمتصلين من الوكلاء، فهي جزء من الواجهة. انشر حدود المعدل وسماحات الاندفاع في وثيقة الاكتشاف حتى يتمكن المخططون من الجدولة. وأعد ترويسات الحصة المتبقية حتى يستطيع الوكيل التراجع قبل الفشل. وافصل المسارات التفاعلية عن مسارات الدفعات؛ فلا ينبغي لوكيل يقوم بالتسوية أن ينافس عملية دفع.
آلية ملموسة: اعرض نقطة نهاية GET /limits تعيد الحصص الحالية ونوافذ الاندفاع وأوقات إعادة الضبط بصيغة قابلة للقراءة آلياً. وأدرج X-RateLimit-Remaining وX-RateLimit-Reset في كل استجابة. عندئذ يستطيع المخطط تنفيذ مجدول بنظام دلو الرمو
المقايضة: صيانة مسارات منفصلة تضيف تعقيداً تشغيلياً وقد تؤدي إلى طاقة غير مستغلة في مسار الدفعات خلال فترات الذروة التفاعلية. البديل — مسار واحد مع تلميحات الأولوية — أبسط في التشغيل لكن أصعب على المخطط في الاستدلال، لأن الأولوية ليست ضماناً. والخيار الصادق يعتمد على ما إذا كانت المنصة تتحمل تجويعاً عرضياً لعمل الدفعات.
تداعيات الحوكمة
كل نقطة نهاية موجهة للوكلاء تحتاج إلى مالك، وسياسة إهمال (deprecation)، وسجل تغييرات مُصدَّر بإصدارات. عامل التغييرات الكاسرة في واجهة وكيل كحادث إنتاجي للأنظمة النهائية. وخلافاً لتغيير واجهة مستخدم موجهة للبشر، لا يستطيع الوكيل التكيّف بقراءة لافتة. سيفشل بصمت أو، الأسوأ، سيتخذ إجراءً خاطئاً.
احتفظ بسجل طلبات قابل لإعادة التشغيل بحيث يمكن حل النزاعات حول ما فعله وكيل ما استناداً إلى الأدلة. وينبغي أن يتضمن السجل مفتاح idempotency، والطلب والاستجابة كاملين، وهوية الوكيل، والطابع الزمني. وهذا ليس للتنقيح فقط؛ إنه أساس الثقة. فعندما يدّعي بائع أن وكيلاً حجز فتحة بشكل مزدوج، يجب أن تكون المنصة قادرة على إظهار ما طُلب بالضبط وما أُعيد بالضبط.
ملاحظة حول الاكتشاف
ينبغي أن تكون الأسطح الموجهة للوكلاء قابلة للاكتشاف دون تدخل بشري. والحد الأدنى هو بيان قابل للقراءة آلياً عند مسار معروف (مثل /.well-known/agent-api) يسرد نقاط النهاية والمخططات ورموز الأخطاء وحدود المعدل وطرق المصادقة. وهذا هو مكافئ خريطة الموقع بالنسبة للوكيل. وبدونه، يصبح كل تكامل مخصصاً.
الخلاصة
التصميم للمتصلين الآليين أولاً لا يعني تجاهل المطورين البشر. إنه يعني جعل العقد صريحاً بما يكفي ليستدل عليه المخطط دون تخمين. إن idempotency والحصص ودلالات الأخطاء ليست ميزات؛ إنها الواجهة. والمنصات التي تتعامل معها كأفكار لاحقة ستجد أن الوكلاء يفشلون بطرق يصعب تنقيحها ويصعب أكثر الوثوق بها. أما التي تنشرها كجزء من العقد فستمكّن صنفاً جديداً من الأتمتة يكون موثوقاً وقابلاً للتدقيق وآمناً لإعادة المحاولة.