بناء وكيل ذكاء اصطناعي دائم باستخدام Vercel eve: دليل TypeScript الكامل

تطلب منك معظم أطر عمل الوكلاء توصيل كل شيء برمجياً: تسجيل الأدوات في مصفوفة، وضبط بيئة التشغيل، وإضافة طابور للمهام الخلفية، وإلحاق المراقبة لاحقاً. أما eve، إطار عمل الوكلاء مفتوح المصدر الذي أعلنت عنه Vercel في 17 يونيو 2026، فيتبع النهج المعاكس. إنه مبني على نظام الملفات: تصف الوكيل بملفات في مواقع تقليدية، ثم يكتشفها eve ويُجمِّع منها بياناً وصفياً (manifest) ويُشغِّل خلفية دائمة تعمل على Vercel Functions.

إذا سبق لك بناء تطبيق Next.js، فسيكون النموذج الذهني مألوفاً — وقد وُصف eve بأنه "Next.js للوكلاء". الملف في مجلد tools/ يصبح أداة قابلة للاستدعاء. والملف في schedules/ يصبح مهمة cron مجدولة. والملف في channels/ يصبح نقطة دخول لـ Slack أو HTTP. لا يوجد تقريباً أي كود تسجيل إضافي.

في هذا الدليل ستبني وكيل مساعد بحثي صغيراً لكن متكاملاً من الصفر، ثم تضيف عليه الأدوات والمهارات والديمومة ووكيلاً فرعياً وجدولة. في النهاية ستفهم شكل مشروع eve بالكامل وتكون جاهزاً للنشر.

المتطلبات الأساسية

قبل البدء، تأكد من توفر:

• Node.js 20+ مُثبَّت
• pnpm (أو npm) متاح في PATH
• إلمام بـ TypeScript وasync/await
• حساب Vercel مجاني (مطلوب فقط لخطوة النشر)
• محرر أكواد (يُنصح بـ VS Code)

لا تحتاج إلى أي مفاتيح API لمزوّدي النماذج لمتابعة الدليل محلياً مع الهيكل المُولَّد. على Vercel، تُحَل سلاسل النماذج عبر AI Gateway باستخدام OIDC، فلا تدير مفاتيح المزوّدين مباشرةً أبداً.

ما الذي ستبنيه

وكيل مساعد بحثي قادر على:

1. الإجابة عن الأسئلة باستخدام أداة web_search مُحدَّدة الأنواع وأداة save_note.
2. تحميل مهارة "تقرير بحثي" متعددة الخطوات فقط عندما تتطلب المهمة العميقة ذلك.
3. العمل كـ جلسة دائمة تنجو من البدايات الباردة (cold starts) وعمليات إعادة النشر.
4. تفويض مهام فرعية مركّزة إلى وكيل فرعي.
5. نشر ملخص أسبوعي وفق جدولة.

سنبنيه تدريجياً ليقف كل مفهوم بذاته.

الخطوة 1: إنشاء هيكل المشروع

أسرع طريق هو واجهة eve السطرية (CLI). تنشئ المجلد وتثبّت التبعيات وتهيّئ Git وتشغّل خادم التطوير:

npx eve@latest init research-agent

عند الانتهاء، أوقف خادم التطوير (لتتمكن من تحرير الملفات بنظافة) وافتح المشروع:

cd research-agent

سترى مجلد agent/ في قلب المشروع. كل ما يُعرِّف وكيلك يعيش تحت agent/. هذا هو التخطيط الذي يكتشفه eve تلقائياً:

research-agent/
├─ agent/
│  ├─ agent.ts          # إعدادات التشغيل (النموذج، الخيارات)
│  ├─ instructions.md   # موجّه النظام الدائم
│  ├─ tools/            # أداة واحدة مُحدَّدة الأنواع لكل ملف
│  ├─ skills/           # إجراءات تُحمَّل عند الطلب
│  ├─ subagents/        # وكلاء أبناء للتفويض
│  ├─ channels/         # نقاط الدخول (HTTP، Slack، ...)
│  ├─ schedules/        # مهام cron
│  └─ sandbox/          # بيئة الحوسبة المعزولة
├─ package.json
└─ README.md

لإضافة eve إلى تطبيق قائم بدلاً من ذلك، شغّل npx eve@latest init . في ذلك المشروع، أو ثبّت الحزم يدوياً:

pnpm add eve ai zod

الخطوة 2: تعريف الوكيل

الوكيل الأدنى هو ملفان فقط. أولاً، موجّه النظام في agent/instructions.md. هذا هو السياق الدائم — اجعله قصيراً وسلوكياً:

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

ثانياً، إعدادات التشغيل في agent/agent.ts. أهم إعداد على الإطلاق هو النموذج:

import { defineAgent } from 'eve';
 
export default defineAgent({
  model: 'anthropic/claude-opus-4.8',
});

تُحَل سلسلة النموذج تلك عبر AI Gateway، فتبديل المزوّد لاحقاً تغيير من سطر واحد — مثلاً openai/gpt-5.4-mini لخيار افتراضي أرخص وأسرع. كما يتولى AI Gateway حالات التحويل الاحتياطي بين المزوّدين، ما يبقي وكيلك مستجيباً حين يمرّ أحد المزوّدين بيوم سيئ.

شغّل خادم التطوير للتأكد من أن كل شيء يُترجَم بنجاح:

pnpm dev

الخطوة 3: إضافة أول أداة

الأدوات إجراءات مُحدَّدة الأنواع يمكن للنموذج استدعاؤها أثناء الدور (turn). القاعدة بسيطة: كل ملف في agent/tools/ هو أداة واحدة، واسم الملف يصبح اسم الأداة الذي يراه النموذج. لا سجل مركزي.

أنشئ agent/tools/web_search.ts. سيرى النموذج هذه كأداة باسم web_search:

import { defineTool } from 'eve/tools';
import { z } from 'zod';
 
export default defineTool({
  description: 'البحث في الويب عن معلومات حديثة حول موضوع ما.',
  inputSchema: z.object({
    query: z.string().min(1).describe('استعلام البحث'),
    limit: z.number().int().min(1).max(10).default(5),
  }),
  async execute({ query, limit }) {
    // استبدل هذا بمزوّد بحث حقيقي في الإنتاج.
    const results = Array.from({ length: limit }, (_, i) => ({
      title: `النتيجة ${i + 1} لـ "${query}"`,
      url: `https://example.com/${encodeURIComponent(query)}/${i + 1}`,
    }));
    return { query, results };
  },
});

لاحظ بعض الأمور:

• inputSchema هو مخطط Zod. يستخدمه eve للتحقق من وسائط النموذج و لتوليد مخطط JSON الذي يراه النموذج، لذا فإن أوصاف كل حقل توجّه النموذج نحو استدعاءات صحيحة.
• execute يستقبل المدخلات المُتحقَّق منها كوسيطه الأول. وما تُرجِعه يُسلسَل ويعود إلى النموذج كنتيجة الأداة.
• لا يوجد حقل name — اسم الملف web_search.ts هو الاسم. لهذا يفضّل eve أسماء الملفات بنمط snake_case.

أضف أداة ثانية ليتمكن الوكيل من حفظ النتائج. أنشئ agent/tools/save_note.ts:

import { defineTool } from 'eve/tools';
import { z } from 'zod';
 
export default defineTool({
  description: 'حفظ ملاحظة بحثية قصيرة للرجوع إليها لاحقاً.',
  inputSchema: z.object({
    title: z.string(),
    body: z.string(),
  }),
  async execute({ title, body }, ctx) {
    // الوسيط الثاني هو سياق الأداة. يكشف عن الصندوق الرملي (sandbox)
    // والتسجيل وبيانات الجلسة. هنا نكتب إلى صندوق الوكيل الرملي.
    await ctx.sandbox.writeFile(
      `notes/${title.replace(/\s+/g, '-').toLowerCase()}.md`,
      `# ${title}\n\n${body}\n`,
    );
    return { saved: true, title };
  },
});

الوسيط الثاني، ctx، هو سياق الأداة. يمنحك الصندوق الرملي للوكيل — بيئة ملفات معزولة بأسلوب bash يحصل عليها كل وكيل eve — إلى جانب التسجيل وبيانات الجلسة. الأدوات المدمجة مثل bash وread_file وwrite_file تستهدف الصندوق الرملي نفسه، فتشترك أدواتك المؤلَّفة والمدمجة في بيئة واحدة.

الخطوة 4: التحدث إلى وكيلك

يكشف eve مسارات HTTP لبدء الجلسات الدائمة وبثّها. ابدأ جلسة بطلب POST:

curl -X POST http://127.0.0.1:3000/eve/v1/session \
  -H 'content-type: application/json' \
  -d '{"message":"ما هو Vercel eve ولماذا يهم؟"}'

يحتوي جسم الاستجابة على continuationToken، وتتضمن الاستجابة ترويسة x-eve-session-id. استخدم معرّف الجلسة هذا للاتصال بالبث الحي، الذي يبثّ أحداث دورة الحياة بصيغة NDJSON بينما يفكّر الوكيل ويستدعي الأدوات وينتج المخرجات:

curl http://127.0.0.1:3000/eve/v1/session/<sessionId>/stream

كل رسالة مستخدم أو حدث خارجي ينشئ دوراً (turn). أثناء الدور يمكن للوكيل استدعاء الأدوات وتحميل المهارات وقراءة وكتابة ملفات الصندوق الرملي والتفويض للوكلاء الفرعيين وبثّ الأحداث. ولأن معرّف الجلسة دائم، يمكنك إعادة الاتصال بالبث نفسه بعد انقطاع والمتابعة من حيث توقفت.

الخطوة 5: فهم الديمومة

هذه ميزة eve البارزة، ولا تكلّفك شيئاً لتفعيلها. تعمل الجلسات فوق Vercel Workflows، التي تحفظ التقدم كسجل أحداث وتعيد تشغيله بشكل حتمي لإعادة بناء الحالة. والنتيجة العملية:

• الجلسة تنجو من البدايات الباردة — إن توقفت الدالة بين الرسائل، تعيد الرسالة التالية تشغيل السجل وتتابع.
• الجلسة تنجو من إعادة النشر — يمكنك إطلاق كود جديد بينما يكون وكلاء طويلو الأمد في منتصف المهمة.
• الجلسة تنجو من التوقفات الطويلة — يمكن لوكيل أن ينتظر ساعات لموافقة بشرية أو نتيجة أداة بطيئة دون إبقاء عملية مفتوحة.

على Vercel، يعمل الوكيل المُجمَّع من Vercel Functions، ولأن الأدوار طويلة الأمد وتُبَث تدريجياً، يستفيد eve من Fluid Compute، المُفعَّل افتراضياً للمشاريع الجديدة. أنت تكتب دوال أدوات async عادية؛ بينما يتولى وقت التشغيل الديمومة.

الخطوة 6: إضافة مهارة للمهام العميقة

الأدوات إجراءات صغيرة مُحدَّدة الأنواع. أما المهارات فهي إجراءات أكبر أو مواد مرجعية يحمّلها النموذج عند الطلب — سير عمل متعدد الخطوات أو معرفة مجال قد تُثقل الموجّه الدائم لو لصقتها في instructions.md.

أنشئ agent/skills/research-report.md:

---
name: research-report
description: إنتاج تقرير بحثي منظّم وموثّق المصادر حول موضوع.
---
 
# إجراء التقرير البحثي
 
اتبع هذه الخطوات عندما يطلب المستخدم تقريراً وافياً:
 
1. استدعِ `web_search` مرتين أو ثلاثاً بزوايا مختلفة للموضوع.
2. جمّع النتائج في 3 إلى 5 محاور.
3. لكل محور، اكتب فقرة قصيرة واستشهد بروابط المصادر.
4. استدعِ `save_note` بالتقرير النهائي ليتمكن المستخدم من استرجاعه لاحقاً.
5. اختم بملخص تنفيذي من فقرة واحدة في الأعلى.

ولأن المهارة منفصلة، لا يسحبها النموذج إلى السياق إلا حين يحتاجها الدور فعلاً — ما يبقي الموجّه الافتراضي خفيفاً والوكيل سريعاً للأسئلة البسيطة. تثبّت مهارات المجتمع في agent/skills/ عبر واجهة مهارات eve السطرية، لكن تأليف مهاراتك الخاصة هو مجرد إفلات ملف Markdown هنا.

الخطوة 7: التفويض عبر وكيل فرعي

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

يقدّم eve نوعين. أداة agent المدمجة تفوّض إلى نسخة من الوكيل الحالي. أما من أجل متخصص، فأعلِن وكيلاً فرعياً تحت agent/subagents/. أنشئ agent/subagents/fact-checker/agent.ts:

import { defineAgent } from 'eve';
 
export default defineAgent({
  model: 'anthropic/claude-opus-4.8',
});

امنحه تعليماته الأضيق في agent/subagents/fact-checker/instructions.md:

أنت مدقّق حقائق. بناءً على ادعاء ومصادره، تحقق مما إذا كانت المصادر تدعم
الادعاء فعلاً. أجب بـ: مدعوم، أو مرفوض، أو غير واضح، متبوعاً بجملة واحدة
للتبرير. لا تتكهّن.

الآن يمكن للوكيل الرئيسي تفويض مهمة تحقق فرعية إلى fact-checker، الذي يعمل كوكيل منفصل. بخلاف المهارة — التي تضيف تعليمات إلى الوكيل الجاري تشغيله — للوكيل الفرعي هوية وسجل ومجموعة أدوات خاصة به. استخدم الوكلاء الفرعيين لموازاة العمل، أو عزل مهمة فرعية محفوفة بالمخاطر، أو منح متخصص مهمة محددة بدقة.

الخطوة 8: تشغيل العمل وفق جدولة

لا تتفاعل الوكلاء مع الرسائل فحسب. الجدولة هي تعبير cron مع معالِج؛ وعلى Vercel تُنشَر كمهمة Vercel Cron. أنشئ agent/schedules/weekly-recap.ts:

import { defineSchedule } from 'eve/schedules';
 
// يعمل كل اثنين الساعة 09:00 بالتوقيت العالمي.
export default defineSchedule({
  cron: '0 9 * * 1',
  async run(ctx) {
    await ctx.startSession({
      message:
        'لخّص الملاحظات البحثية المحفوظة خلال الأيام السبعة الأخيرة وانشر ملخصاً.',
    });
  },
});

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

الخطوة 9: إضافة قناة

حتى الآن تحدثت إلى الوكيل عبر HTTP الخام. القنوات نقاط دخول إلى وقت تشغيل الوكيل نفسه — تبدأ الجلسات وتوجّه أحداث المنصة إلى أدوار وتطبّق المصادقة والتنسيق الخاصين بالمنصة. HTTP مدمجة؛ وقنوات المنصات أمر واحد في الـ CLI لكل منها. لإضافة Slack:

npx eve@latest channels add slack

هذا يكتب agent/channels/slack.ts، وهو محوّل صغير يربط أحداث Slack بأدوار الوكيل. تأتي Slack وDiscord وTeams وTelegram وTwilio وGitHub وLinear افتراضياً، وتغطي defineChannel من eve/channels القنوات المخصّصة. الفكرة الأساسية: الوكيل نفسه يخدم كل السطوح. لا تعيد بناء المنطق لكل منصة — كل قناة مجرد ملف محوّل رفيع، وتعيش أسرار القنوات في متغيرات البيئة.

الخطوة 10: النشر على Vercel

صُمِّم eve للعمل على Vercel دون بنية تحتية إضافية. أبسط طريق قائم على Git:

1. ادفع المشروع إلى مستودع Git متصل بـ Vercel.
2. يكتشف Vercel مشروع eve ويبني الوكيل المُجمَّع كـ Vercel Functions.
3. يحلّ AI Gateway سلاسل نماذجك عبر OIDC — لا مفاتيح مزوّدين لضبطها.

تفضّل الـ CLI؟ ثبّتها وانشر مباشرةً:

npm i -g vercel
vercel deploy

بعد النشر، افتح Agent Runs في لوحة تحكم Vercel. يحصل كل مشروع eve على المراقبة دون أي إعداد: الجلسات والأدوار واستدعاءات الأدوات والاستدلال والتوقيت واستهلاك الرموز كلها مرئية. وإن أردت أيضاً تتبّعات AI SDK في خلفية OpenTelemetry خارجية، أضف ملف agent/instrumentation.ts.

اختبار تنفيذك

تحقق من كل طبقة محلياً قبل النشر:

1. إقلاع الوكيل: pnpm dev يبدأ دون أخطاء ويطبع الرابط المحلي.
2. تسجيل الأدوات: ابدأ جلسة تسأل "ابحث عن أخبار إطار eve" وتأكد أن البث يُظهر استدعاء أداة web_search.
3. تحميل المهارة: اطلب "تقريراً بحثياً كاملاً عن X" وتأكد أن مهارة research-report تُسحَب (مرئية في أحداث دورة الحياة).
4. الديمومة: أوقف خادم التطوير في منتصف جلسة، أعد تشغيله، وأعد الاتصال بالبث بمعرّف الجلسة نفسه — تستأنف الجلسة.
5. الوكيل الفرعي: اطلب من الوكيل "تدقيق هذا الادعاء مقابل مصادره" وتأكد من التفويض إلى fact-checker.

استكشاف الأخطاء وإصلاحها

أداة لا تُستدعى أبداً. تحقق من نص description و.describe() لكل حقل — يعتمد عليها النموذج ليقرر متى يستدعي أداة. الأوصاف الغامضة تؤدي إلى أدوات غير مستخدمة.

أخطاء النموذج حول بيانات الاعتماد محلياً. قد تحتاج محلياً إلى مفتاح مزوّد في بيئتك؛ أما على Vercel فيتولى AI Gateway + OIDC ذلك. راجع README الخاص بالهيكل لمعرفة متغير البيئة المحلي الدقيق.

عدم تطابق اسم الملف مع اسم الأداة. تذكّر أن اسم الملف هو اسم الأداة. أعد تسمية الملف، لا حقل name، واستخدم snake_case.

الجدولة لا تنطلق محلياً. تُنشَر جداول cron كمهام Vercel Cron — تعمل على البيئة المنشورة، لا بالضرورة في كل تشغيل تطوير محلي. شغّل المعالِج يدوياً في التطوير لاختباره.

الخطوات التالية

• استبدل أداة web_search الوهمية بمزوّد حقيقي (مثل واجهة بحث أو Firecrawl) وصِل بيانات الاعتماد عبر Vercel Connect.
• أضف تكامل connections/ لخدمة خارجية مُحدَّدة الأنواع لتبقى بيانات الاعتماد بعيدة عن موجّهك وكود أدواتك.
• استكشف الصندوق الرملي أكثر — شغّل كوداً يولّده النموذج في microVM مؤقت عبر أداة bash المدمجة.
• قارن نموذج eve المبني على نظام الملفات بأطر مبنية على الكود مثل Vercel AI SDK لتقرّر ما يناسب فريقك.

الخلاصة

يعيد eve صياغة تطوير الوكلاء حول نظام الملفات: الأدوات والمهارات والوكلاء الفرعيون والقنوات والجداول كلها مجرد ملفات في مجلدات تقليدية، ويجمّعها eve في خلفية دائمة تعمل على Vercel Functions. حصلت على مساعد بحثي عامل بأدوات مُحدَّدة الأنواع، ومهارة عند الطلب، وجلسات دائمة، ووكيل فرعي متخصص، وجدولة أسبوعية، ومسار نشر — دون أن تدير أنت الطوابير أو بيئات التشغيل أو مفاتيح المزوّدين.

أكبر تحوّل ذهني هو الفصل بين الأدوات والمهارات: إجراءات مُحدَّدة الأنواع يستدعيها النموذج مقابل إجراءات يقرؤها. أتقِن ذلك تبقَ وكلاؤك سريعة في الأدوار البسيطة وقادرة في العميقة. من هنا، أدخِل تكاملات حقيقية، وأضف قنوات للسطوح التي يعيش عليها مستخدموك فعلاً، ودَع ديمومة Vercel تحمل العمل طويل الأمد.

المصادر

• eve — وثائق Vercel
• مفاهيم eve — وثائق Vercel
• التعريف بـ eve — مدونة Vercel
• vercel/eve على GitHub
• eve.dev — البدء