Claude API وManaged Agents: ما الذي يمكن حذفه من بنية Cloudflare؟

ما الجديد في Anthropic SDK 0.100 إلى 0.102 لمستخدمي Claude API؟

ثلاثة إصدارات في 8 أيام وسّعت نطاق Anthropic Python SDK أكثر مما حدث خلال الأشهر الستة السابقة. والتواريخ مهمة؛ فأي بيئة إنتاج ثبّتت الإصدار anthropic==0.99.x فاتها تشغيل Managed Agents بالكامل خلال دورة تطوير واحدة.

أضاف v0.100.0 (6 مايو 2026) دعم تعدد الوكلاء وoutcomes وwebhooks والتحقق من vault ضمن مساحة الأسماء beta. أما البنية الأهم فهي: يعيد client.beta.managed_agents.sessions.create(thread=..., outcome=..., metadata=...) قيمة session_id، ثم يعمل بصورة غير متزامنة على بنية Anthropic التحتية. وبذلك لم تعد حلقة التنسيق مسؤوليتك.

أضاف v0.101.0 (11 مايو 2026) عميل AWS الخاص بـClaude Platform on AWS، وحدّث جميع أمثلة cookbook إلى claude-sonnet-4-5-20250929. إذا كانت بنيتك تعمل على Bedrock، فهذا هو الإصدار المطلوب؛ فقد وصل دعم متغير البيئة ANTHROPIC_BEDROCK_SERVICE_TIER بخياراته (default/flex/priority) هنا، لا في 0.100.

أضاف v0.102.0 (13 مايو 2026) أنواع BetaManagedAgentsSearchResultBlock، وتشخيصات cache الخاصة بالإصدار التجريبي من prompt cache، والتحقق المبكر من Pydantic iterators. وما زالت واجهة أنواع blocks تتغير، وهذا هو السبب الأهم لعدم نقلي شيفرة تعدد الوكلاء حتى الآن.

الميزة الأبرز هي outcomes. تكتب rubric، ثم يقيّم وكيل مستقل النتيجة وفقها، ويعيد الوكيل المحاولة إلى أن يجتاز التقييم. وتفيد اختبارات Anthropic الداخلية بتحسن يصل إلى +10 نقاط في نجاح المهام مقارنة بحلقات prompting المعتادة، و+8.4% في إنشاء ملفات docx، و+10.1% في ملفات pptx. وتنسجم هذه النتيجة مع ما أراه في Critic Durable Object لدي: إعادة prompting واحدة مرفقة بملاحظات المُحكِّم تعادل تقريبًا الانتقال درجة كاملة إلى نموذج أفضل.

أما النصف الآخر فهو webhooks. تُرسل 8 أحداث للجلسة إلى عنوان URL تسجله في Claude Console: session.status_run_started وsession.status_idled وsession.status_rescheduled وsession.status_terminated وsession.thread_created وsession.thread_idled وsession.thread_terminated، ثم الحدث الأهم session.outcome_evaluation_ended. يبدأ سر التوقيع بـwhsec_… ولا يظهر إلا مرة واحدة عند الإنشاء. ويجري التحقق عبر client.webhooks.unwrap(payload, signature, secret).

وصل أيضًا تنسيق الوكلاء المتعددين، لكنه ما زال خلف طلب وصول إلى research preview. وسأعود إلى سبب عدم تفعيله لدي.

ماذا يعني ذلك للمؤسسين غير التقنيين؟

باتت Anthropic تشغّل الوكيل نيابة عنك. أنت تكتب rubric (مثل: «هل بلغ المقال 2,000 كلمة، واستشهد بـ3 مصادر أولية، واجتاز تعبير de-AI النمطي؟»)، ثم يقيّم وكيل Anthropic المخرجات ويعيد تشغيل الوكيل إلى أن ينجح. وهكذا يتوقف مهندسك عن كتابة حلقة إعادة المحاولة.

لهذا أثران في التكلفة. أولًا، يقل عدد حلقات إعادة المحاولة المصممة يدويًا في قاعدة الشيفرة، فتتراجع ساعات المهندس الخبير اللازمة لصيانتها. ثانيًا، تزيد المحاولات داخل جلسة Anthropic، وتُحاسب كل واحدة منها بسعر $0.08 لكل ساعة جلسة فوق تكلفة tokens. وما إذا كان المحصّلة وفرًا يتوقف بالكامل على مدة الجلسات.

الصياغة الصريحة هي: إذا كان فريقك يطلق الإصدار v1 من منتج قائم على الوكلاء، فإن Managed Agents تستبدل نحو 40% من شيفرة التنسيق التي سيبنيها مهندسك الخبير لولا ذلك. أما إذا سبق لكم إطلاق منتج، فستستبدل جزءًا أصغر، لكن جانب webhooks يلغي حلقة الاستطلاع الموجودة على الأرجح في مكان ما من النظام.

السؤال الذي ينبغي طرحه على المدير التقني هذا الأسبوع: «هل ما زلنا نستطلع اكتمال المهمة، أم انتقلنا إلى session.outcome_evaluation_ended؟» إذا كانت الإجابة «ما زلنا نستطلع»، فهذه إعادة هيكلة تستغرق نصف يوم وتخفض تكلفة البنية التحتية وزمن الاستجابة بخطوة واحدة.

بنية Cloudflare التي أشغّلها اليوم

لتوضيح ما يمكن حذفه، تتكون البنية من Hono worker واحد على Cloudflare Workers، مع استهداف ES2021 وربط Static Assets، ويتصدر 6 Durable Objects، واحدًا لكل روتين نشر. وهي Editorial وDiscovery وWriter وDistribution وMaintenance وManager، إلى جانب كائن سابع هو ManualIntake يدعم واجهة الإدارة.

يعمل كل روتين عبر واحد من 6 Cloudflare Workflows: PublishWorkflow وWriteArticle وPublishArticle وEnrichIdea وDiscoverIdeas وDistributeArticle. وأكثرها عملًا هو PublishWorkflow، إذ يضم 8 خطوات idempotent بالترتيب: التحقق، والتأسيس على المصادر، والتوليد، والتنظيف، والحفظ، والفهرسة، والغلاف، والنشر. وتُغلّف كل خطوة I/O بما يلي:

const result = await step.do(
  "generate-article",
  { retries: { limit: 3, backoff: "exponential" } },
  async () => env.WRITER.generate(brief)
);

تحتفظ D1 بالحالة المرجعية (انتقالات editorial_brief.status: من dispatched إلى drafting ثم published / failed). وتتولى Vectorize تضمينات كل block على حدة (Gemini-2 بأبعاد 768d وتنسيق استرجاع asymmetric). وتمر كل مكالمة مدفوعة للنماذج عبر نقطة تحكم واحدة هي callAi(env, ctx, runner)؛ إذ تسجل في ai_call_log حقول agent_id وworkflow_instance_id وidea_id لتجميع التكلفة، وتفرض سقفًا يوميًا قدره $20 وسقفًا قدره $1 لكل instance.

هذه هي بنية Durable Objects الستة التي وثقتها سابقًا. وما يهم في الانتقال إلى Managed Agents هو موضع منطق إعادة المحاولة. وهو موجود في موضعين:

1. إعادة المحاولة في خطوات Workflow (تكلفتها محدودة وتصبح مجانية إذا نجحت المكالمة الأساسية): انقطاعات الشبكة، وحدود المعدل، وأخطاء 5xx المؤقتة من المزوّدين الخارجيين.
2. حلقة "judge-and-retry" مكتوبة يدويًا في clean.ts: شغّل Writer، ثم Critic، وإذا تحقق score < 0.75 فأعد prompting مع ملاحظات Critic، بحد أقصى 3 محاولات.

Managed Agents تستبدل الموضع الثاني. أما الأول فيبقى.

كيف يتيح SDK 0.100 حذف 280 سطرًا؟

حلقة judge-and-retry في src/worker/workflows/publish/clean.ts هي أوضح موضع يقابل outcomes. تضم اليوم نحو 120 سطرًا من شيفرة التنسيق: استدعاء Writer، ثم Critic وفق rubric مخزنة في editorial_brief.rubric_md، وتحليل الدرجة، والتفرع بحسب الحد المطلوب، وإعادة prompting مع إرفاق الملاحظات كـsystem block، ثم التكرار حتى 3 مرات. ويضيف Critic نفسه 80 سطرًا أخرى ضمن Durable Object تشمل hibernation hooks وSQLite منفصلة لكل instance لحفظ سجل rubric ومفاتيح idempotency لكل محاولة. ثم تضيف عملية تجميع ai_call_log لكل محاولة في callAi.ts نحو 40 سطرًا أخرى، لأن كل محاولة تُسجّل على حدة قبل أن تجمعها لوحة المتابعة.

تختصر الكتل الثلاث كلها في مكالمة Managed Agents واحدة:

const session = await anthropic.beta.managedAgents.sessions.create({
  thread: { messages: [{ role: "user", content: brief.body_md }] },
  outcome: {
    rubric: brief.rubric_md,
    evaluator: "claude-sonnet-4-5-20250929"
  },
  metadata: { brief_id: brief.id, workflow_instance: ctx.instanceId }
});
return { session_id: session.id, status: "pending" };

هذا كل شيء. تعمل الجلسة حتى الاكتمال بصورة غير متزامنة لدى Anthropic. ويتولى معامل outcome العمل الذي كان ينفذه Critic DO: يقيّم وكيل مستقل المخرجات وفق rubric، ويعيد تشغيل الوكيل الأساسي إلى أن ينجح.

أما الشيفرة التي أضيفها فهي route واحدة عند /api/admin/webhooks/managed-agents للتحقق من توقيع whsec_…، ثم التفرع عند event.type === "session.outcome_evaluation_ended" وكتابة النتيجة مجددًا إلى D1.

app.post("/api/admin/webhooks/managed-agents", async (c) => {
  const raw = await c.req.text();
  const event = await anthropic.webhooks.unwrap(
    raw, c.req.header("anthropic-signature")!, c.env.WEBHOOK_SECRET
  );

  if (event.type !== "session.outcome_evaluation_ended") {
    return c.json({ ok: true });
  }

  await c.env.DB.update(editorial_brief).set({
    status: event.outcome.passed ? "published" : "failed",
    body_md: event.result.body,
    session_cost_usd: event.session.usage.total_cost_usd
  }).where(eq(editorial_brief.id, event.session.metadata.brief_id));

  return c.json({ ok: true });
});

أي 40 سطرًا، مع توقيع متحقق منه وidempotency يعتمد على brief_id.

صافي الفرق: حذف 240 سطرًا من شيفرة التنسيق، وحذف ربط Durable Object واحد من wrangler.json، وحذف ملف migration واحد. في المقابل، تضاف 40 سطرًا لمعالجة webhook وسر واحد في Cloudflare Secrets Store.

تواصل نقطة الاستطلاع عند GET /api/admin/workflows/:id/status العمل. لكنها تقرأ الآن حالة الجلسة من D1، بعد أن يملأها webhook، بدلًا من env.PUBLISH_WORKFLOW.get(id).status(). لا تتغير واجهة المستخدم، ولا تلاحظ لوحة الإدارة أي فرق.

تبقى ملاحظة مهمة: أغلفة إعادة المحاولة step.do تظل حول جميع خطوات I/O الأخرى. إنشاء صورة الغلاف، وإعادة التحقق في Vercel، وتفريغ cache في Cloudflare؛ لا تستفيد أي منها من outcome rubrics، بينما تستفيد جميعًا من التخزين المؤقت الآمن لإعادة التشغيل في Workflows. فلا تحذف ما يعمل بالفعل.

الملف الوحيد الذي سأبقيه، ولماذا تنقلب معادلة التكلفة عند التوسع

يبقى callAi.ts. فالسقف اليومي $20، والسقف لكل instance هو $1. وكل مكالمة مدفوعة للنماذج تمر عبره، سواء كانت مباشرة أو عبر AI Gateway أو Managed Agents.

وهنا تتضح أهميته. تحاسب Managed Agents على 3 محاور: tokens بالأسعار المعتادة، إضافة إلى $0.08 لكل ساعة جلسة، ثم $10 لكل 1000 عملية بحث ويب. وفق حجمي الحالي، أي 6 روتينات نشر ومقال واحد لكل تشغيل ونحو 3 دقائق للجلسة، تبلغ تكلفة ساعة الجلسة قرابة $0.004 لكل مقال فوق تكلفة tokens. وهي تكلفة ضئيلة.

تنقلب المعادلة عندما تطول الجلسات. جلسة Anthropic Skills مدتها 4 ساعات تعني $0.32 لتشغيل الجلسة وحده، فوق تكلفة tokens. ومع 50 جلسة من هذا النوع يوميًا، تصبح التكلفة $480 شهريًا لساعات الجلسات فقط قبل tokens. أما جلسة بحث متعددة الخطوات تبقى خاملة ساعة في طابور بحث ويب، فتكلف $0.08 لم تكن ستدفعها سابقًا. ووقت خمول الجلسة أثناء انتظار خدمة لاحقة يُحاسب أيضًا؛ إذ تقول وثائق Anthropic إن القياس يتم بالملّي ثانية، لكن العداد يظل دائرًا.

تفرض نقطة التحكم سقفًا صارمًا لا توفره لوحة Managed Agents. فاللوحة تعرض تكلفة الجلسة بعد وقوعها. أما callAi.ts فيطلق NonRetryableError في منتصف Workflow قبل بدء الجلسة إذا أظهر تقدير pre-flight أنها ستتجاوز السقف اليومي.

تقدير pre-flight متحفظ:

async function estimateSessionCost(brief: Brief): Promise<number> {
  const tokenEstimate = brief.body_md.length / 3.5;
  const inputCost = (tokenEstimate / 1_000_000) * 3.0;
  const outputCost = (tokenEstimate * 1.5 / 1_000_000) * 15.0;
  const sessionHourEstimate = (brief.expected_minutes / 60) * 0.08;
  const safetyMargin = 1.4;
  return (inputCost + outputCost + sessionHourEstimate) * safetyMargin;
}

حساب التكلفة لكل ساعة جلسة هو أسرع موضع تنحرف فيه إعدادات المهندس الفرد عن السيطرة. من دون السقف، يلتهم وكيل واحد منفلت ميزانية اليوم قبل أن تلاحظ؛ وهذا بالضبط نوع السلوك الذي قد تشجعه حلقة إعادة المحاولة في outcome عندما تكون rubric شديدة الصرامة. وقد رأيت ذلك بنفسي.

أبقِ نقطة التحكم. مرّر sessions.create() من خلالها، وسجّل تقدير pre-flight قبل بدء الجلسة، ثم طابقه مع event.session.usage.total_cost_usd من حمولة webhook عند انتهاء الجلسة.

الانتقال الذي لن أنفذه بعد: تنسيق وكلاء الذكاء الاصطناعي المتعددين

تنسيق الوكلاء المتعددين هو الميزة الأبرز من Anthropic Dev Day. يقسم الوكيل القائد المهمة، ويوزع المهام الفرعية على وكلاء متخصصين لكل منهم نموذج وprompt وأدوات خاصة به. ويعمل الوكلاء الفرعيون بالتوازي على نظام ملفات مشترك، ثم يجمع الوكيل القائد النتائج. نظريًا، هذا ما يفعله Manager DO لدي اليوم تمامًا: يوزع العمل بالتوازي عبر DO RPC على Writer وDiscovery وDistribution، ولكل منها حالة SQLite خاصة، فيما تعمل R2 وD1 بوصفهما «نظام الملفات» المشترك.

هناك 3 أسباب للتريث.

أولًا: تقلب API. ما زال تنسيق الوكلاء المتعددين في research preview ويتطلب طلب وصول منفصلًا. كما وصل BetaManagedAgentsSearchResultBlock للتو في 0.102، وما زالت واجهة أنواع blocks الخاصة بنتائج تعدد الوكلاء تتغير. والانتقال الآن يعني إعادة كتابة التكامل مع كل تحديث SDK خلال الإصدارين أو 3 إصدارات المقبلة. استقرت واجهة webhook في 0.100، أما تعدد الوكلاء فما زال يتحرك.

ثانيًا: نظام الملفات المشترك مؤقت ومحصور في الجلسة. يختفي نظام الملفات المشترك داخل جلسة Managed Agents عند انتهائها. بينما تظل R2 وD1 دائمتين بين جميع روتيناتي، ويمكن الاستعلام عنهما من أي worker، كما تصمدان أمام تعطل الجلسة. وإلى أن يصبح نظام الملفات المشترك دائمًا، أو أتمكن من تركيب R2 مباشرة داخل session sandbox، سيكون هذا تراجعًا في المزايا بالنسبة إلى عبء عملي.

ثالثًا: تقسيم الأدوار بين الوكيل القائد والوكلاء الفرعيين لدى Anthropic يفرض نمطًا محددًا. يكون Editorial DO هو القائد في بعض الأيام، عندما يعمل روتين نشر، ويكون ندًا في أيام أخرى، عندما ترسل واجهة الإدارة brief وينضم Editorial إلى pipeline في منتصفها. سأضطر إلى تسطيح تفاوت مفيد كي ألائم تجريدًا مستضافًا.

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

قائمة الانتقال الدقيقة من SDK 0.100 إلى 0.102

يستغرق انتقال Discovery فترة بعد ظهر واحدة، ويحتاج Writer إلى فترة أخرى، ثم تتبعه بقية الأجزاء. ثبّت 0.102.0، وسجّل webhook، واحذف Critic DO، وأبقِ نقطة التحكم.