Anthropic API 2026-10-21: رحّل العقود دون أعطال

إصدار Anthropic API رقم 2026-10-21 ليس تغيير Header فقط، بل ترحيل عقد كامل. فهو يحذف معاملات Sampling، ويشدد مواضع Documents وCitations، ويعيد تسمية حقول Admin وAnalytics، ويتزامن مع إصدارات رئيسية للـSDK تغير المصادقة والأنواع وCompaction وواجهات قديمة. لذلك يجب على الفرق الإنتاجية جرد الاستخدام، وإضافة Contract Tests، وتشغيل Canary، وفصل Rollback عن ترحيلات البيانات.

نشرت Anthropic إصدار API وإصدارات SDK وCLI الجديدة في 21 أكتوبر 2026. الحقائق أدناه مأخوذة من Release Notes ومرجع Versioning ودليل الترحيل الرسمي، وتم التحقق منها في 25 أكتوبر 2026. أما ترتيب النشر وObservability وضوابط المخاطر فهي توصيات هندسية.

ما الذي يتغير فعلًا؟

الإصدار الجديد متاح على Claude API وClaude Platform on AWS ومساري Claude على Google Cloud، وكذلك Microsoft Foundry. ويدعمه Amazon Bedrock لنماذج Claude 4.7 فأحدث؛ أما النماذج الأقدم على Bedrock فيجب أن تبقى مؤقتًا على إصدار API الحالي حتى ترقية النموذج.

في Messages وToken Counting وMessage Batches حُذفت ثلاثة معاملات: temperature وtop_p وtop_k. إرسال أي منها يعيد HTTP 400 حتى لو كانت القيمة مساوية لقيمة افتراضية سابقة. كما يرفض الإصدار Document Block الموضوع مباشرة داخل رسالة Assistant. ويرفض Text Block داخل رسالة User إذا احتوى citations غير فارغة، بما في ذلك النص داخل search_result؛ بينما تظل إعدادات تفعيل الاستشهاد على Documents وSearch Results صحيحة.

تغيرت كذلك أسماء حقول في Admin وEnterprise Analytics. وهذه مخاطرة Parser صامتة: قد ينجح الطلب، لكن Consumer متساهل يسجل Null أو يسقط البيانات.

إصدار API وSDK Major تغييران منفصلان

نشرت Anthropic أول الإصدارات الداعمة: Python 2.0.0 وTypeScript 1.0.0 وC# 13.0.0 وGo 2.0.0 وJava 3.0.0 وPHP 1.0.0 وRuby 2.0.0 وant CLI 2.0.0. ترسل هذه الإصدارات 2026-10-21 افتراضيًا، لكنها تحمل أيضًا تغييرات لا تعتمد على عقد الشبكة.

ترسل SDK مفتاح API الآن داخل Authorization: Bearer بدل X-Api-Key. تقبل Claude API كلاهما، لكن Gateway أو Test Double أو قاعدة Redaction أو Middleware تتوقع X-Api-Key فقط قد تفشل. وأصبح Client يحمل Credential واحدة بدل إرسال API Key وAuth Token معًا. كما قُسمت Message Types بحسب Role، ولذلك قد يفشل بناء النوع القديم أو توريثه رغم استمرار عمل Dictionary مكافئ.

أُزيل Client-side Compaction من Tool Runner في TypeScript وRuby لصالح Server-side Compaction. وأزيلت Text Completions القديمة من عدة SDK ومن CLI. وانتقلت استدعاءات Models التي تحمل Beta Headers إلى Beta Namespace. كما تغير الترخيص في الإصدارات الجديدة من MIT إلى Apache 2.0، وهو مهم لجرد التبعيات والتراخيص رغم عدم حاجته إلى تعديل Runtime.

تعامل مع العمل على محورين:

1. Wire Contract: سلوك الطلب والاستجابة الذي يختاره anthropic-version.
2. Client Contract: الأنواع والمصادقة والHelpers والDefaults والMethods المحذوفة في SDK Major.

اختبار التركيبة النهائية وحدها يخفي أي محور سبب المشكلة.

ابنِ جرد أثر قبل تعديل الكود

ابحث في كل Service وShared Library وProxy وBatch Worker عن:

• Header anthropic-version وإصدارات SDK؛
• temperature وtop_p وtop_k؛
• Document Blocks في Assistant وCitation Arrays المرسلة من User؛
• أسماء حقول Admin وAnalytics داخل الكود وSQL Models وDashboards؛
• X-Api-Key وAuthorization وترتيب اختيار Credentials؛
• Text Completions وBeta Models وTool Runner Compaction؛
• Switch صارم على Streaming Events أو Enum-like Values.

لا تعتمد على كود التطبيق فقط. قد تحتوي API Gateways وService Mesh وLog Pipelines وFixtures وGenerated Clients على الافتراضات القديمة. سجل كل Call Site مع المالك وCloud Path وModel Family وحجم المرور وحساسية البيانات وطريقة Rollback.

معمارية ترحيل آمنة

ضع اختيار API Version خلف Configuration بدل نشر Header ثابت في كل مكان. وافصله عن Model ID وعن Package Lock. يجب أن يحول Request Adapter نية التطبيق إلى عقد المزود، بينما يعرض Response Adapter Schema داخلية واحدة لبقية المنتج.

type ClaudeWireVersion = "2023-06-01" | "2026-10-21";

function buildClaudeRequest(input: AppRequest, version: ClaudeWireVersion) {
  const body = {
    model: input.model,
    max_tokens: input.maxTokens,
    messages: normalizeRoles(input.messages)
  } as Record<string, unknown>;

  if (version === "2023-06-01" && input.legacySampling) {
    Object.assign(body, input.legacySampling);
  }

  assertNoAssistantDocuments(body);
  assertNoUserCitationPayloads(body);
  return { version, body };
}

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

استبدل افتراضات Sampling بعقد منتج واضح

لا يوجد في الإصدار الجديد إعداد بديل لقيم Sampling غير الافتراضية. توضح Anthropic أن الطلب يستخدم Defaults، ومنها Temperature 1.0، عند حذف هذه المعاملات. إذا اعتمد Workflow على Temperature منخفضة لزيادة الثبات، فقس تغير السلوك بدل اختراع بديل غير موثق.

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

Contract Tests تكشف الأعطال الحقيقية

أنشئ Golden Fixtures لكل Capability نشطة: Messages العادية، وTool Use، والصور، والDocuments، وSearch Results، وCitations، وToken Counting، وBatches، وAdmin/Analytics. شغلها على Test Project بالإصدارين عندما يكون ذلك مدعومًا.

اختبر على الأقل:

• النجاح وأخطاء 400 المتوقعة للحقول المحذوفة؛
• إعادة إرسال Multi-turn History تحتوي Assistant Citations قديمة؛
• Documents في مواضع User الصحيحة وAssistant الخاطئة؛
• Strict Deserialization لكل حقل Admin أعيدت تسميته؛
• Default Workspace مقابل Organization-wide API Keys؛
• مصادقة Proxy وSecret Redaction مع Authorization؛
• Streaming Parser يقبل Event Variants مستقبلية غير معروفة؛
• Batch Items وToken Count تستخدمان Payload مطبعة نفسها.

لا تقارن النص المولد Byte for Byte. قارن Schema Validity وTool Contracts وموضع Citation وSafety Route والزمن واستهلاك Tokens ونتائج Evaluation الخاصة بالمهمة.

انشر اعتمادًا على دليل المرور

استخدم أربع مراحل:

1. Compile وFixtures: حدّث Types في Branch واجعل Contract Tests تمر بلا Production Traffic.
2. Shadow: ابنِ طلبات ممثلة بالعقد الجديد وقارن النتائج إذا سمحت سياسة الخصوصية وDuplicate Inference.
3. Canary: وجّه Cohort صغيرة وصريحة إلى SDK والإصدار الجديدين، واجعل Side Effects Idempotent حتى لا يكرر Rollback أداة أو دفعًا.
4. Progressive: وسع حسب Workload أو Tenant أو Region بعد نجاح بوابات الخطأ والجودة والتكلفة.

افصل Deploy Rollback عن Data Rollback. فإذا كان Admin Collector سيخزن كائن scope الجديد، فأضف الأعمدة المتوافقة قبل تحويل Readers؛ لا تنفذ Rename مدمرًا في Release قطع API نفسه.

Observability وبوابات القرار

ضع Tags للمقاييس تشمل اسم التكامل الداخلي وSDK Major وAPI Version وCloud Path وModel Family. راقب HTTP 400 حسب فئة خطأ مطبعة، وأخطاء المصادقة وParser وTool Validity وفشل عناصر Batch والزمن وTokens وEvaluation Score.

لا تضع API Keys أو Prompts كاملة أو بيانات شخصية داخل Tags. احتفظ بـRequest IDs من المزود وHash لشكل الطلب المنقح. بوابة Rollback الجيدة ليست “زاد Error Rate” فقط؛ عرّف حدود Contract Failure وتراجع الجودة وتغير التكلفة قبل بدء Canary.

الأمان وتغييرات Gateway

يستحق انتقال Authentication Header مراجعة أمنية صريحة. حدّث Allowlists وWAF وOutbound Proxy وSecret Scanners وLog Redaction. وتأكد أن Gateway يحذف Credential الذي ينهيه قبل Forwarding. ينص دليل Anthropic على أن طلب Claude API يجب أن يقدم Credential واحدة؛ لا تمرر Gateway Bearer Token بوصفه Provider Credential بالخطأ.

أزال ant CLI Flags المفاتيح من Command Line لأن Arguments تظهر في Shell History وProcess Listings. استخدم Secret Manager للبيئة أو خيارات stdin أو Login Flow. هذا تحسن أمني، لكن Automation ما تزال تمرر --api-key ستتوقف ويجب إصلاحها بوضوح.

أفضل الممارسات وAnti-patterns

أفضل الممارسات

• ثبّت SDK Major وAPI Version صراحة في أدلة النشر.
• طبّع طلبات المزود واستجاباته خلف Adapters مختبرة.
• أضف حقول التخزين الجديدة قبل تحويل Readers.
• استخدم Cohort ثابتة في Canary مع Rollback سريع للإصدار.
• راجع Authentication وRedaction في Gateways.
• أعد Evaluation للجودة عندما يتغير Sampling.

Anti-patterns

• تحديث SDK وHeader بقفزة إنتاج واحدة بلا مراقبة.
• حذف الحقول المرفوضة عالميًا دون معرفة مالكها.
• اعتبار workspace_id=null هو Default Workspace بعد الترحيل.
• افتراض أن HTTP 200 يعني أن Dashboard قرأت الحقول الجديدة.
• تسجيل Authorization Header أثناء Debugging.
• استبدال Authorization حتمي بمخرجات Model.

متى تؤجل Cutover؟

أجل Workload محددة إذا كانت تعتمد على نموذج Bedrock أقدم، أو تحتاج Sampling غير افتراضيًا ثبتت قيمته تجاريًا، أو تفتقر إلى تغطية Documents وCitations وAdmin Fields. التأجيل ليس استراتيجية دائمة؛ اجعل الاستثناء ضيقًا، وسجل العائق، واختبر نموذجًا أو Workflow مدعومًا بديلًا.

لا تؤجل كل الخدمات بسبب مسار Legacy واحد. اختيار الإصدار يجب أن يكون داخل Integration أو Request Adapter حتى تنتقل الأحمال المتوافقة بصورة مستقلة.

قائمة تنفيذية

1. احصر الإصدارات والنماذج والسحب والحقول وSampling وافتراضات المصادقة.
2. افصل عمل SDK Major عن Wire Version.
3. ابنِ Request وResponse Adapters مع Assertions للأشكال المرفوضة.
4. أضف Fixtures لـMessages وBatches وCitations وAdmin وAnalytics.
5. حدّث Gateways وRedaction لمصادقة Bearer.
6. شغل Quality Evaluation للمسارات التي استخدمت Sampling.
7. نفذ Shadow حيث يسمح، ثم Canary بـCohort ثابتة وبوابات Rollback.
8. وسع تدريجيًا، ولا تغلق الاستثناءات إلا بعد إثبات.

اقرأ أيضًا: Anthropic User Profiles وWebhooks، ومعمارية Claude على Google Cloud، وحفظ Provenance في استشهادات RAG، ومكتبة هندسة AI.

المراجع الأولية

• Anthropic — Claude Platform release notes
• Anthropic — Migrating to API version 2026-10-21
• Anthropic — API versioning
• Anthropic — Using the Messages API
• Anthropic — Model deprecations
• Unsplash License
• Eric Stoynov — صورة Server Rack مرخّصة

إعداد: Noor Yasser