عملاء Mastra المستدامون: دليل تعليمي لعام 2026 TypeScript

Mastra هو إطار عمل TypeScript لبناء وكلاء الذكاء الاصطناعي (AI agents)، وتعمل ميزة Durable Agents (في مرحلتها التجريبية) على تغليف الوكيل العادي بحيث يستمر تدفق البيانات (stream) الخاص به حتى في حالة انقطاع الاتصال¹. يقوم هذا الدليل ببناء وكيل من الصفر، وتشغيله فعلياً، وإنهاء اتصال العميل في منتصف التدفق، ثم إعادة الاتصال — مع عرض مخرجات الطرفية (terminal) الحقيقية لإثبات نجاح العملية.

ملخص

تقوم Durable Agents في Mastra (نسخة تجريبية، أضيفت في @mastra/core@1.45.0²) بتغليف Agent عادي بحيث ينجو تدفق البيانات الخاص به من انقطاعات الاتصال: يمكنك إعادة الاتصال باستخدام observe(runId)، وسيقوم Mastra بإعادة تشغيل كل حدث مفقود من الذاكرة المخبأة (cache) قبل استئناف البث المباشر، دون الحاجة لإعادة تشغيل دورة الوكيل من البداية. ستقوم ببناء وكيل، وبدء تدفق، ومحاكاة انقطاع الاتصال بعد 3 أحداث، ثم إعادة الاتصال من "عميل" ثانٍ، ومشاهدة وصول جميع الأحداث الثمانية — الثلاثة التي فقدتها بالإضافة إلى 5 أحداث جديدة — بالترتيب. بيئة التشغيل: Node.js 22.13+³، @mastra/core@1.51.0⁴. وقت البناء: 25-35 دقيقة.

ما ستتعلمه

• ما الذي تغيره Durable Agents فعلياً مقارنة بـ Mastra Agent العادي، ومتى يكون ذلك مهماً
• كيفية تغليف وكيل باستخدام createDurableAgent() وقراءة الـ runId، والـ output، والـ cleanup() الخاص به
• كيفية محاكاة انقطاع الاتصال وإعادة الاتصال باستخدام observe(runId) — مع مخرجات حقيقية تظهر عملية إعادة التشغيل (replay)
• كيفية تشغيل البرنامج التعليمي بالكامل بدون مفتاح API، باستخدام أداة اختبار النماذج الوهمية (mock-model) الداخلية في Mastra
• الفرق بين ثلاثة أنواع من التنفيذ المستدام: createDurableAgent()، و createEventedAgent()، و createInngestAgent()
• ما الذي لا يزال مفقوداً إذا استخدمت الذاكرة المخبأة الافتراضية في الذاكرة (in-memory cache)، وما الذي يوفره لك Redis بدلاً من ذلك

ما هو Mastra

Mastra هو إطار عمل TypeScript مفتوح المصدر لبناء وكلاء الذكاء الاصطناعي، وسير العمل (workflows)، وأنابيب RAG، وقد تم بناؤه بواسطة الفريق الذي قام سابقاً ببناء Gatsby⁵. أغلقت الشركة جولة تمويل أولية (seed round) بقيمة 13 مليون دولار في مارس 2025 (أُعلن عنها علناً في 8 أكتوبر 2025) بعد الانضمام إلى دفعة Y Combinator لشتاء 2025، ثم جمعت 22 مليون دولار في جولة Series A بقيادة Spark Capital في 9 أبريل 2026 — ليصل إجمالي التمويل إلى 35 مليون دولار — بالتزامن مع الإطلاق التجاري لمنصة Mastra (Studio و Server و Memory Gateway) المبنية فوق إطار العمل مفتوح المصدر⁶⁷.

في إعلان أكتوبر 2025، ذكرت Mastra أن إطار العمل نما من حوالي 10,000 إلى 150,000 عملية تحميل أسبوعية مستمرة من npm في عامه الأول (من أكتوبر 2024 إلى أكتوبر 2025) — وهي وتيرة وصفتها الشركة بأنها ثالث أسرع نمو لأي إطار عمل JavaScript وجدت بيانات نمو مماثلة له⁶. وتضع إحصائيات التحميل الخاصة بـ npm نفسها API حزمة @mastra/core عند 937,152 تحميلاً للأسبوع من 19 إلى 25 مايو 2026⁸، ويسرد مستودع GitHub الخاص بالمشروع أكثر من 23,000 نجمة حتى وقت كتابة هذه السطور — وقد أظهر موقع Mastra نفسه أرقاماً أعلى بشكل ملحوظ وغير متسقة (من 25.3 ألف إلى 26.2 ألف، حيث لم تتفق أي صفحتين) عبر صفحات مختلفة أثناء البحث لهذا المنشور، لذا تم استخدام صفحة مستودع GitHub المباشرة هنا كمصدر أكثر موثوقية⁹.

تشمل الشركات التي وصفت علناً استخدام Mastra كلاً من Replit و SoftBank و PayPal و Adobe اعتباراً من إعلان أكتوبر 2025⁶، و Brex و Sanity و Factorial و Indeed و MongoDB و Workday و Salesforce اعتباراً من منشور Series A في أبريل 2026⁷.

لا يتطلب أي من ذلك متابعة هذا البرنامج التعليمي — إنه مجرد سياق يوضح لماذا يستحق إطار عمل قد لا تكون استخدمته بعد نظرة فاحصة. الموضوع الفعلي هو ميزة واحدة محددة وجديدة إلى حد ما.

المشكلة التي تحلها Durable Agents

يقوم Mastra Agent العادي ببث استجابته عبر نفس اتصال HTTP الذي بدأ الطلب. إذا انقطع هذا الاتصال — مثل فقدان عميل الهاتف للإشارة، أو تحديث تبويب المتصفح، أو انتهاء مهلة موازن الحمل (load balancer) لطلب طويل — يختفي التدفق. لا يوجد استئناف من حيث توقف؛ يجب على المتصل بدء الدورة من جديد¹.

تغير Durable Agents ذلك. تقوم createDurableAgent() بتغليف Agent موجود بحيث تعمل حلقة الوكيل داخل سير عمل (workflow) في Mastra بدلاً من أن تكون مرتبطة بالطلب. وبينما تنتج الحلقة أحداثاً، يتم نشرها في موضوع PubSub مفتاحه هو runId ويتم تخزينها مؤقتاً. يمكن للمتصل الاشتراك في هذا الموضوع، وفصل الاتصال، ثم إعادة الاتصال لاحقاً — من نفس العميل أو عميل مختلف — عن طريق استدعاء observe(runId)، والذي يعيد تشغيل كل حدث مخزن مؤقتاً قبل الانتقال إلى التسليم المباشر¹.

هذه الميزة في مرحلة beta وقت كتابة هذا الدليل؛ وتحمل وثائق Mastra تحذيراً صريحاً بأن "واجهات برمجة التطبيقات (APIs) قد تتغير في الإصدارات المستقبلية"¹⁰، لذا تعامل مع توقيعات الطرق (method signatures) المحددة هنا كلقطة من إصدار @mastra/core@1.51.0، وليس كعقد دائم.

الإعداد

يتطلب هذا البرنامج التعليمي فقط @mastra/core — لا حاجة لقاعدة بيانات، ولا Redis، ولا Docker، و (كما سترى بعد قليل) لا حاجة لمفتاح API الخاص بـ LLM.

mkdir mastra-durable-demo && cd mastra-durable-demo
npm init -y
npm install @mastra/core@1.51.0 TypeScript tsx zod
npm install --save-dev @types/node

تتطلب @mastra/core إصدار Node.js >=22.13.0³ وتقبل zod@^3.25.0 أو ^4.0.0 كاعتمادية نظيرة (peer dependency)⁴. أضف ملف tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "types": ["node"]
  },
  "include": ["*.ts"]
}

إن خيار skipLibCheck: true ليس مجرد كود روتيني — راجع قسم "الأخطاء الشائعة" أدناه لمعرفة سبب أهميته. قم بتعيين "type": "module" في ملف package.json أيضاً، لأن الأمثلة تستخدم await في المستوى الأعلى.

بناء وكيل عادي

ابدأ بـ Agent بسيط. هذا هو نفس العنصر الأساسي الذي تبدأ به جميع دروس Mastra — لا يوجد شيء "مستدام" فيه بعد:

import { Agent } from '@mastra/core/agent';

const agent = new Agent({
  id: 'virtualDr',
  name: 'Virtual Dr',
  instructions: 'You are a careful medical research assistant.',
  model: 'anthropic/claude-sonnet-4-6', // أي سلسلة نماذج يدعمها موجه Mastra
});

عند استدعائه مباشرة، سيعيد agent.stream(...) استجابة مرتبطة بهذه العملية وهذا الاستدعاء. إذا قمت بانتظارها (await) وماتت العملية، أو انقطع اتصال المتصل، فإن تلك الاستجابة تضيع. هذه هي الفجوة التي تسدها Durable Agents.

تغليفه باستخدام createDurableAgent()

تأخذ createDurableAgent()، من @mastra/core/agent/durable، وكيل Agent موجود وتعيد DurableAgent بنفس شكل .stream() بالإضافة إلى طريقتين جديدتين: .observe() و .resume()¹¹.

import { createDurableAgent } from '@mastra/core/agent/durable';

const durableAgent = createDurableAgent({ agent });

هذه هي خطوة التغليف بالكامل. ومن الجدير بالذكر أن هذا لا يتطلب بناء مثيل تطبيق Mastra({...}) كامل — مثال توثيقات Mastra يقوم بربط واحد، ولكن durableAgent.stream() يعمل بشكل مستقل، وهو ما يفعله الكود أدناه فعلياً. أنت تحتاج فقط إلى مثيل Mastra إذا كنت تقوم أيضاً بتشغيل طبقة خادم HTTP.

قم بتشغيله، ثم اقطع الاتصال عمداً

هذا هو الجزء الذي يسهل إثباته عملياً أكثر من مجرد القراءة عنه. يقوم السكريبت أدناه بدورين: "العميل A" يبدأ تدفقاً (stream) ويتوقف عمداً عن القراءة بعد 3 أحداث (محاكاةً لاتصال مقطوع، بما في ذلك عدم استدعاء cleanup() — لأن الانقطاع الحقيقي لن يتاح له الفرصة). ثم يعيد "العميل B" الاتصال باستخدام الـ runId الذي التقطه العميل A قبل أن "يسقط".

import { Agent } from '@mastra/core/agent';
import { createDurableAgent } from '@mastra/core/agent/durable';
import { createMockModel } from '@mastra/core/test-utils/llm-mock';

async function main() {
  const model = createMockModel({
    mockText: 'The first-line treatment for adult migraine is usually a triptan or an NSAID.',
  });

  const agent = new Agent({
    id: 'virtualDr',
    name: 'Virtual Dr',
    instructions: 'You are a careful medical research assistant.',
    model,
  });

  const durableAgent = createDurableAgent({ agent });

  console.log('--- Client A: starting stream() ---');
  const clientA = await durableAgent.stream(
    "What's the first-line treatment for adult migraine?",
  );
  console.log('runId:', clientA.runId);

  const seenByA: string[] = [];
  let chunkCount = 0;
  for await (const chunk of clientA.output.fullStream) {
    chunkCount++;
    seenByA.push(chunk.type);
    // Simulate client A's connection dropping after the 3rd event
    if (chunkCount === 3) {
      console.log('Client A: simulating a dropped connection after', chunkCount, 'chunks');
      break;
    }
  }
  console.log('Client A saw chunk types:', seenByA);

  console.log('\n--- Client B: reconnecting with observe(runId) ---');
  const clientB = await durableAgent.observe(clientA.runId);
  const seenByB: string[] = [];
  for await (const chunk of clientB.output.fullStream) {
    seenByB.push(chunk.type);
  }
  console.log('Client B saw chunk types (replayed + live):', seenByB);

  const finalText = await clientB.output.text;
  console.log('\nFinal text (via reconnected client):', finalText);

  clientB.cleanup();
}

main().catch((err) => {
  console.error('FAILED:', err);
  process.exit(1);
});

تجاهل createMockModel للحظة — سيتم شرحه في القسم التالي. قم بتشغيله:

npx tsx durable-demo.ts

المخرجات الحقيقية من هذا السكريبت بالضبط، دون تعديل:

--- Client A: starting stream() ---
runId: 09345c55-61da-4eb8-8238-6f4709b15e2d
Client A: simulating a dropped connection after 3 chunks
Client A saw chunk types: [ 'start', 'step-start', 'response-metadata' ]

--- Client B: reconnecting with observe(runId) ---
Client B saw chunk types (replayed + live): [
  'start',
  'step-start',
  'response-metadata',
  'text-start',
  'text-delta',
  'text-end',
  'step-finish',
  'finish'
]

Final text (via reconnected client): The first-line treatment for adult migraine is usually a triptan or an NSAID.

هذه هي الميزة وهي تعمل من البداية للنهاية. اتصال العميل A يسقط بعد 3 أحداث. يعيد العميل B الاتصال باستخدام سلسلة runId فقط ويرى جميع الأحداث الثمانية — الثلاثة التي حصل عليها العميل A بالفعل، والتي أعيد تشغيلها من الذاكرة المخبئية (cache)، متبوعة بالخمسة التي حدثت بعد "مغادرة" العميل A. لم يقم أحد بإعادة تشغيل دور العميل من البداية، ولم يلمس العميل B كائن clientA الأصلي أبداً.

الاختبار بدون مفتاح API

العرض التوضيحي أعلاه لا يستدعي أي مزود نماذج حقيقي. createMockModel()، المستورد من @mastra/core/test-utils/llm-mock، هو أداة تشحنها Mastra داخلياً لمجموعة اختباراتها الخاصة. لا تظهر هذه الأداة في أي مكان في التنقل أو المحتوى الخاص بموقع التوثيقات العام، ولديها إعدادات أنواع (types) معطلة فعلياً: ملف package.json الخاص بـ @mastra/core يعلن عن مسار types لهذا التصدير يشير إلى ./dist/test-utils/llm-mock.d.ts، ولكن هذا الملف غير موجود فعلياً في الحزمة المنشورة — لقد تحققنا من ذلك باختبار مباشر لنظام الملفات (test -f)، وليس فقط من خلال قراءة خريطة exports.

في الخلفية، تقوم createMockModel() ببناء كائن حقيقي يستوفي واجهة LanguageModelV2 الخاصة بـ AI SDK (doGenerate/doStream)، وهو ما تم تأكيده من خلال قراءة ملف dist/test-utils/llm-mock.js المترجم مباشرة، لذا فإن Agent الخاص بـ Mastra يقبله تماماً كما يقبل نموذج مزود حقيقي — وهذا هو السبب في أن آلية التنفيذ المستمر أعلاه تعمل فعلياً، بدون استدعاءات شبكة وبدون فواتير.

بسبب فقدان ملف الأنواع المعلن، يحتاج TypeScript إلى إعلان وحدة محيطية (ambient module declaration) صغيرة للتوقف عن التذمر:

// durable-agent-mock.d.ts
declare module '@mastra/core/test-utils/llm-mock' {
  import type { Agent } from '@mastra/core/agent';
  export function createMockModel(
    config: { mockText: string },
  ): ConstructorParameters<typeof Agent>[0]['model'];
}

هذا يعكس نمطاً تم تغطيته بالفعل في هذه المدونة لإطار عمل مختلف — حيث تشحن AI SDK من Vercel نموذجاً وهمياً (mock model) عاماً وموثقاً لنفس الغرض¹² (ذلك المنشور يغطي MockLanguageModelV3؛ وقد شحنت AI SDK من Vercel منذ ذلك الحين الإصدار v7، والذي يكون المكافئ الحالي له هو MockLanguageModelV4، وهو ما تم تأكيده مقابل توثيقات AI SDK المباشرة أثناء مراجعة هذا المنشور¹³).

المكافئ في Mastra حقيقي ويعمل، ولكن لأنه غير موثق وغير محدد الأنواع، تعامل معه كوسيلة للتحقق من تمديدات الكود أثناء التطوير، وليس كـ API عام ومستقر لبناء اختبارات الإنتاج. بالنسبة للنشر الحقيقي، قم بتبديل model مرة أخرى إلى سلسلة مزود مثل 'anthropic/claude-sonnet-4-6' أو مثيل SDK لمزود حقيقي — لن يتغير أي شيء آخر في كود العميل المستمر (durable-agent).

import { createDurableAgent } from '@mastra/core/agent/durable';
import { RedisServerCache } from '@mastra/Redis';

const durableAgent = createDurableAgent({
  agent,
  cache: new RedisServerCache({ url: 'Redis://localhost:6379' }),
});