Claude Opus 5.5 ينفذ مهامًا تستغرق 18 ساعة: كيف تصمم واجهات API للوكلاء طويلة التشغيل

كل مهلة زمنية في منظومتك تفترض عميلًا يستسلم في النهاية. يُغلق لسان المتصفح. يصل مهمة CI إلى حدّها الزمني. يبتعد إنسان. الإعدادات الافتراضية التي ورثتها عن موازن التحميل والبوابة ومكتبة HTTP الخاصة بك صُممت لمُتصل تُقاس صبره بالثواني.

تقول Anthropic إن Claude Opus 5.5 يبقى على المهمة 18 ساعة أو أكثر.

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

هذه مشكلة تصميم واجهة برمجة تطبيقات، وليست مشكلة نموذج. إليك ما ينكسر، وما يجب تغييره.

ما نشرته Anthropic فعليًا

أرقام البائع للنموذج الجديد، حتى نتناقش من نفس الورقة:

المعايير من نفس الإعلان: Terminal-Bench 4.0 بنسبة 66.4%، وOSWorld 2.0 بنسبة 81.8%، وAutomationBench بنسبة 40.0%، وFrontierCode v1.1 بنسبة 54.4%، وCursorBench 4.0 بنسبة 57.8%، وHumanity’s Last Exam بنسبة 67.7% مع الأدوات، وChartography بنسبة 89.0%، وGDPval-AA v2.1 عند 1846 Elo، وانخفاض بنسبة 85% في محاولات تجاوز الحدود الناجحة.

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

ستة افتراضات تتوقف عن الصمود

لكل منها حلّ ممل، ومفهوم جيدًا، وعادةً ما يُتجاوز لأن لا شيء فرض المشكلة. هناك شيء يفرضها الآن.

أعِد مقابض، لا عملًا

التغيير الأعلى قيمة: أي عملية يمكن أن تتجاوز بضع ثوانٍ تُعيد مورد مهمة فورًا بدلًا من إبقاء الاتصال معلّقًا.

POST /v1/reports HTTP/1.1
Host: api.example.com
Idempotency-Key: 01J9Z4KCQ7M3XN2YB8V6H0
Content-Type: application/json

{"dataset": "orders_2026_q3", "format": "parquet"}

HTTP/1.1 202 Accepted
Location: /v1/jobs/job_01J9Z4KD
Retry-After: 5
Content-Type: application/json

{
  "id": "job_01J9Z4KD",
  "status": "queued",
  "created_at": "2026-09-23T04:12:09Z",
  "api_version": "2026-08-01"
}

ثم يحمل مورد الحالة كل ما يحتاجه الوكيل لتقرير ما سيفعله بعد ذلك:

{
  "id": "job_01J9Z4KD",
  "status": "running",
  "progress": { "completed": 41200, "total": 180000, "unit": "rows" },
  "started_at": "2026-09-23T04:12:11Z",
  "updated_at": "2026-09-23T05:47:02Z",
  "expires_at": "2026-09-24T04:12:09Z",
  "retry_after_seconds": 15,
  "result_url": null,
  "error": null
}

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

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

اجعل الـ idempotency يعيش أطول من المهمة

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

ثلاثة تغييرات تكلّف قليلًا جدًا:

1. انشر النافذة. أعِد تاريخ الانتهاء في الاستجابة ليتسنى للمتصل الاستنتاج حوله، بدلًا من توثيقه مرة واحدة والأمل.
2. قل عندما أعدت التشغيل. رأس Idempotency-Replayed: true يحوّل عملية لا تنفذ شيئًا بصمت إلى شيء يمكن للوكيل التصرف بناءً عليه.
3. ارفض عدم التطابق بصوت عالٍ. نفس المفتاح مع جسم مختلف يعني أن المتصل فقد تتبع حالته الخاصة. أعِد 409 مع بصمة الطلب الأصلية بدلًا من تقديم نتيجة قديمة.

HTTP/1.1 200 OK
Idempotency-Replayed: true
Idempotency-Expires: 2026-09-24T04:12:09Z

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

افترض أن بيانات الاعتماد تنتهي في منتصف المهمة

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

أعِد 401 مع تحدٍّ WWW-Authenticate: Bearer error="invalid_token" عندما ينتهي الرمز، واحفظ 403 لهوية تفتقر إلى الإذن. يتعامل الوكلاء مع هذين بشكل مختلف جدًا: أحدهما يعني التجديد والمتابعة، والآخر يعني التوقف والإبلاغ. دمجها في فشل عام هو كيف تحصل على وكيل يحرق أربع ساعات في إعادة محاولة شيء لن يُسمح له به أبدًا.

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

تعامل مع البث كقابل للاستئناف، لا كاتصال

تنقطع عمليات البث الطويلة. افترض ذلك، وصمّم إعادة الاتصال بدلًا من الاتصال.

بالنسبة لأحداث الخادم المُرسَلة، يعني ذلك إعطاء كل حدث id تصاعديًا، واحترام رأس الطلب Last-Event-ID عند إعادة الاتصال، وإصدار تعليق إبقاء على فاصل أقصر من أضيق مهلة خمول بينك وبين العميل. اذكر مفاتيح الإعداد في وثائقك الخاصة، لأن القارئ عليه أن يذهب ويغيّرها: idle_timeout.timeout_seconds في موازن التحميل AWS، وproxy_read_timeout في nginx، وtimeout في خدمة Cloud Run. النقطة ليست قيمة محددة. بل أن القيمة موجودة، وأقصر من العمل، ولم ينظر إليها أحد منذ إنشاء الخدمة. يغطي دليل بث SSE الخاص بنا صيغة الإرسال؛ والجزء الخاص بالوكيل هو الاستئناف.

رؤوس تحديد المعدل مهمة أكثر من المعتاد أيضًا. يتيح RateLimit-Limit وRateLimit-Remaining وRateLimit-Reset للنموذج أن ينظّم إيقاعه عبر تشغيل طويل، ووجود Retry-After على كل 429 يزيل التخمين. الوكيل الذي يُعطى رقمًا يحترمه. والوكيل الذي لا يُعطى شيئًا يخترع تراجعًا، ولن يكون اختراعه أفضل من اختراعك.

جانب التكلفة قرار تصميمي

انظر مرة أخرى إلى صف التسعير. يكلّف الإدخال $4 لكل مليون رمز والقراءة المخزّنة مؤقتًا $0.20، فرق عشرين ضعفًا على الجزء من الحمولة الذي يعيد الوكيل إرساله أكثر من غيره، وعلى نافذة سياق بحجم 1M تصبح الأرقام المطلقة كبيرة بسرعة. عمليات كتابة الذاكرة المؤقتة بسعر $5 تعني أن المرور الأول يكلّف أكثر قليلًا من قراءة عادية، لذا فإن التخزين المؤقت يدفع فقط عندما يكون البادئة مُعاد استخدامها حقًا. على مدى ثماني عشرة ساعة، فهي كذلك.

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

الحجم ليس افتراضيًا. أفصحت OpenAI أن باحثها الوسيط ينفق أكثر من $600 يوميًا على وكلاء البرمجة، مع النسبة المئوية التسعين فوق $7,000 يوميًا. هذا ما يكلّفه العمل الوكيلي المستمر عندما لا يحسّنه أحد، وهو جزء من السبب وراء أن ثلاثة إطلاقات نماذج في يومين كلها قدّمت التكلفة لكل مهمة بدلًا من التكلفة لكل رمز. حساب متى يسترد التخزين المؤقت تكلفته موجود في تفصيل تكلفة التخزين المؤقت لـ Opus 5.5.

اختبر المسار الطويل قبل أن يجده وكيل

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

في Apidog، صمّم دورة الحياة الكاملة كسيناريو اختبار بدلًا من طلب واحد: أكّد أن استدعاء الإنشاء يُعيد 202 مع Location وRetry-After، وكرّر نقطة نهاية الحالة حتى الحالة النهائية، وأكّد أن progress.completed لا يتحرك للخلف أبدًا. هذا التأكيد الأخير يلتقط أخطاء حقيقية أكثر من أي فحص لرمز الحالة، لأن التقدم غير التصاعدي هو ما يقنع الوكيل بالبدء من جديد.

ثم اكسره عن قصد باستخدام خادم محاكاة. قدّم مهمة تبقى running لعشرين استعلامًا ثم تفشل. قدّم 429 بدون Retry-After وراقب ما يفعله عميلك. قدّم 401 في منتصف الطريق لتأكيد أن مسار التجديد يعمل أثناء وجود مهمة جارية. يحافظ اختبار SSE في Apidog على اتصال بث مفتوحًا ويؤكّد على الأحداث الفردية، وهي الطريقة العملية الوحيدة للتحقق من أن استئناف Last-Event-ID يُعيد المؤشر الصحيح بدلًا من إعادة التشغيل من الصفر. اربط السيناريو بـ CI بحيث يفشل تغيير مهلة مستقبلي في اختبار بدلًا من تشغيل ليلي لدى عميل. Apidog مجاني للبدء، والسيناريو الذي تبنيه مرة واحدة يغطي كل نقطة نهاية طويلة التشغيل تملكها.

القائمة المختصرة

• العمليات الطويلة تُعيد 202 مع مقبض مهمة، وليس اتصالًا معلّقًا أبدًا
• استجابات الحالة تحمل تقدمًا، ووحدة، وفاصل استعلام يختاره الخادم، وتاريخ انتهاء
• المهام تثبّت إصدار API الذي أُنشئت به
• نوافذ الـ idempotency منشورة، وإعادات التشغيل موسومة، وإعادة استخدام مفتاح مع جسم متغيّر تُعيد 409
• 401 للرموز المنتهية يمكن تمييزه عن 403 للمرفوضة
• المهام تنتمي إلى هوية، لا إلى نسخة رمز
• عمليات البث تحمل معرّفات أحداث، وتحترم Last-Event-ID، وترسل إبقاءات داخل أقصر مهلة خمول على المسار
• كل 429 يحمل Retry-After، ورؤوس تحديد المعدل موجودة دائمًا
• المواصفة وتعريفات الأدوات تتسلسل بشكل مستقر بالبايت لتبقى ذاكرات التخزين المؤقت لدى العميل دافئة

لم يخترع Opus 5.5 أيًا من هذه المتطلبات. لقد أزال آخر عذر لتجاوزها، لأن العميل الذي كان يستسلم قبل أن يجد الشقوق يعمل الآن عبرها مباشرةً لمدة ثماني عشرة ساعة.