بني وخدّم زملاء ديال الذكاء الاصطناعي فالسيرفر ديالك باستعمال useAgent

تحذير ألفا: useAgent مازال فمرحلة التطوير النشيط. الـAPIs والـschemas يقدرو يتبدلو بين الإصدارات، لذلك ثبّت tag ديال الإصدار ملي كتكون الاستقرار مهم.

شنو هو useAgent؟

useAgent هي منصة مفتوحة المصدر ديال زميل فالخدمة بالذكاء الاصطناعي، كتخليك تشغّل agents بحال Claude Code وCodex وOpenCode. عوض ما يرجعو غير أجوبة حوارية، الـagents كيخدمو فبيئات Linux معزولة وقدرو يسلّمو مواقع إلكترونية كاملة، عروض تقديمية، جداول بيانات، تقارير بحث، وpull requests مجرّبين.

كل thread كيتعطى ليه workstation فيها terminal وrepositories وbrowser وdesktop باين من خلال noVNC. الـruns كيتسجلو على شكل timelines مبنية على الأحداث فـPostgres، وهاد الشي كيخليها دائمة، قابلة لإعادة التشغيل، وقابلة للفحص من بعد ما تسالي.

الميزات الرئيسية

• واجهة وحدة لعدة agents: المحركات الخاصة بكل provider كتتواصل من خلال عقد موحّد ديال الأحداث.
• تنفيذ دائم: الـruns كيبقاو خدامين حتى من بعد إعادة تشغيل الـbackend، والاسترجاع يقدر يعاود يفحص الجلسات النشيطة ويتبنّى الخدمة اللي سالات.
• بيئات Linux معزولة: كل thread كيتعطى ليه workstation مستقلة. Daytona وCubeSandbox كينفّذو العقد المشترك ديال الـsandbox.
• بوابة أدوات موثوقة: بيانات الدخول كاتبقى فـcontrol plane وما كتدخلش لـsandbox ديال الـagent.
• موافقة بشرية: استدعاءات الأدوات المدمّرة كتوقف حتى تتم الموافقة عليها فالواجهة الويب ولا فـSlack، ومن بعد كتكمّل بقدرة مرتبطة بالوسيط ومخصصة لاستعمال واحد.
• مهارات مبنية على GitHub: الفرق يقدرو يستوردو ملفات SKILL.md مْرقّمة بالإصدارات، يزامنو التغييرات، ويرتبو المهارات المرتبطة داخل دورات الـagent.
• السياق التنظيمي: استرجاع المعرفة كيشمل الاستشهادات، وذاكرة الفريق كتستعمل مسار تعلّم كيراجعو الإنسان.
• Artifacts أصلية: المنصة كتدعم ملفات DOCX وXLSX وPPTX وPDF فيها إصدارات، مع renderers أصلية.
• قنوات دخول متعددة: الخدمة تقدر توصل من تطبيق الويب أوSlack أوREST API أوالجداول الزمنية.

كيفاش كتخدم البنية

useAgent كتفصل control plane اللي كتستضيفو بنفسك على البيئة اللي كيخدم فيها الـagent. قنوات الدخول كتخلق الـruns من نفس المسار. محولات المحركات كتحوّل النشاط الخاص بكل provider لأحداث موحّدة، وكل thread كيتعيّن ليه sandbox معزولة.

كاينين ثلاثة خصائص معمارية مهمين بزاف:

1. المحركات قابلة للتبديل: تبديل المحرك ما كيحتاجش تبديل التمثيل المشترك ديال الـthreads ولا الـartifacts ولا الذاكرة.
2. Postgres هو مصدر الحقيقة: كل run كيتخزن كسجل ديال الأحداث، وهاد الشي كيتيح إعادة التشغيل والفحص بشكل دقيق من بعد إعادة التشغيل.
3. الأسرار كاتبقى برا الـsandboxes: التكاملات كتعرض كأدوات مكتوبة الأنواع من خلال بوابة موثوقة، وبيانات الدخول كاتتخزن غير فـcontrol plane.

تنظيم المستودع

• frontend/ فيها واجهة المنتج الخاصة بالجلسات والمهارات وplaybooks والـwiki والـartifacts والأتمتة والإعدادات.
• backend/ فيها المصادقة وتنسيق الـruns ومحولات المحركات والـsandboxes والمعرفة والذاكرة والـartifacts والموصلات.
• packages/ فيها عقود الأحداث المشتركة وworkpieces وصيغ الـartifacts والـrenderers والحزم المرتبطة بها.
• docs-site/ فيها موقع التوثيق.
• infra/self-host/ فيها أدوات النشر المستقلة على providers ومرجع Terraform ديال Hetzner.
• memory/ فيها خدمة ذاكرة الفريق الاختيارية.

المتطلبات المسبقة

التثبيت المحلي ديال التطوير كيحتاج Bun وPostgres 16 ولا أحدث، مع إضافة pgvector. صور Postgres العادية ديال الحاويات ما فيهاش pgvector، لذلك استعمل صورة مفعّل فيها pgvector.

خاصك حتى Docker إلا كنت ناوي تشغّل أمر حاوية قاعدة البيانات المرفق. نفّذ الخطوات التالية من جذر مستودع useAgent.

الخطوة 1: شغّل Postgres مع pgvector

إلا ما كانتش عندك قاعدة بيانات متوافقة، شغّل وحدة فـDocker:

docker run -d --name useagent-pg -p 5432:5432 \
  -e POSTGRES_HOST_AUTH_METHOD=trust pgvector/pgvector:pg16
export DATABASE_URL=postgres://postgres@localhost:5432/postgres

الأمر الأول كيعرّض Postgres على المنفذ 5432. والثاني كيعيّن سلسلة الاتصال اللي كيستعملها التطبيق. إعداد trust مناسب للتطوير المحلي؛ أما بيئات الإنتاج خاصها تستعمل بيانات دخول مؤمّنة بالشكل المناسب.

الخطوة 2: ثبّت اعتماديات مساحة العمل

الاعتماديات كتتثبّت بشكل مستقل فالحزم المشتركة وworkspaces ديال الـbackend والـfrontend:

for workspace in \
  packages/agent-harness packages/artifact-workspace \
  packages/agent-client packages/artifact-formats packages/conformance \
  backend frontend; do
  (cd "$workspace" && bun install)
done

الخطوة 3: شغّل الـbackend والـfrontend

حلّ جلسات terminal منفصلة وشغّل جوج عمليات التطوير:

bun run dev:backend

bun run dev:frontend

الـbackend كيوفّر API وخدمة تنسيق على المنفذ 3201. والـfrontend كيخدم على المنفذ 3400 وكيحوّل الطلبات اللي تحت /api/* للـbackend.

حلّ http://localhost:3400 فالمتصفح باش تدخل للواجهة. إعدادات المزوّد والـsandbox تقدر تختلف، لذلك تبع التوثيق الحالي ديال useAgent ملي تربط محرّك agent ولا تجهّز بيئة التنفيذ ديالو.

الخطوة 4: التحقّق من قاعدة الكود

شغّل مدقّق الأنواع على مستوى المستودع من بعد التثبيت ولا قبل ما تقدّم أي تغيير:

bun run typecheck

هاد الأمر كيغطي كل الحزم فالمستودع وكيعاون يلقط التغييرات غير المتوافقة بين العقود المشتركة، والواجهة الخلفية، والواجهة الأمامية.

الاستعمال الأساسي

إنشاء تشغيل ديال agent

1. حلّ الواجهة على المنفذ 3400.
2. استعمل محرّر agent ووصف النتيجة النهائية اللي محتاج.
3. بدا التشغيل وتبع الخط الزمني الحي ديال الأحداث.
4. راقب نشاط الطرفية، والمتصفح، وسطح المكتب، ولا مساحة العمل مع تقدّم agent.
5. راجع أي بطاقة ديال الموافقة قبل ما تسمح بعملية مدمّرة باستعمال أداة.
6. جمع الأثر النهائي ولا الخدمة على المستودع اللي رجعاتها الجلسة.

تقدر تصيغ المهمة حول نتيجة ملموسة، بحال:

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

فخدمة البرمجيات، حدّد التنفيذ المتوقع وكيفاش غادي يتم التحقّق منو:

نفّذ التغيير المطلوب فالمستودع، شغّل الاختبارات المناسبة، ووجّه الخدمة المكتملة للمراجعة.

هاد الأمثلة ديال المهام مكتوبة باللغة الطبيعية، وماشي صيغة أوامر خاصة. الأدوات المتاحة بالضبط لأي تشغيل كتتعلّق بالمحرّك، والـsandbox، ومصادر المعرفة، والمهارات، والتكاملات المهيّأة.

الخدمة عبر Slack

ملي كيكون تكامل Slack الأصلي مهيّأ، يقدرو المستخدمين يذكرو agent باش يبدا الخدمة. الأجوبة، والمرفقات، والآثار، وطلبات الموافقة كيبقاو فخيط Slack. هاد الشي كيوفّر نفس مسار التشغيل ديال واجهة الويب، مع بقاء التعاون فالقناة الأصلية.

استعمال المعرفة والمهارات التنظيمية

المعرفة، ومحتوى الويكي، وذاكرة الفريق يقدرو يوفّرو سياق خاص بالمنظمة مع الاستشهادات. حتى التعليمات القابلة لإعادة الاستعمال تقدر تستوردها من GitHub كمهارات بإصدارات عبر SKILL.md. يقدر useAgent يعاود يزامن هاد المهارات أوتوماتيكياً ويرتّب المهارات المرتبطة بكل دور.

الاستضافة الذاتية ديال useAgent

يقدر useAgent يخدم فوق أي مضيف Linux، بما فيه AWS وGoogle Cloud وAzure وHetzner ولا خوادم فعلية. المستودع فيه سكريبتات نشر مستقلة على المزوّد، وزايد مضيف مرجعي ديال Hetzner كيتبنى بأمر واحد باستعمال Terraform.

من بعد ما تجهّز مضيف Linux والقيم المطلوبة، عيّط على سكريبت النشر من المستودع:

SERVER_IP=<host-ip> PG_PASSWORD=... OPENROUTER_API_KEY=... \
  infra/self-host/deploy-app.sh /path/to/this/repo

عملية التجهيز كتتاصل بالآلة المستهدفة عبر SSH. شوف infra/self-host/README.md للدليل الكامل ديال الإنتاج والتفاصيل المطلوبة ديال البيئة، وما تعتبرش المثال المختصر إعداداً أمنياً كاملاً.

اختيار بيئة تشغيل sandbox

• Daytona: خدمة sandbox مُدارة تقدر ترتابط بمضيف ديال طبقة التحكّم فوق أي سحابة. الـREADME كيصفها بأنها أسهل اختيار للبداية.
• CubeSandbox: بيئة تشغيل مستضافة ذاتياً للمنظمات اللي باغية sandboxes فوق العتاد ديالها وكتحتاج بقاء البيانات فالمكان ديالها.

الجوج ديال البيئات كيدوزو من نفس عقد sandbox، وهاد الشي كيخلّي طبقة التحكّم تنسّق خدمة agent بلا ما تربط نموذج التشغيل الأساسي ديالها بمزوّد sandbox واحد.

نصائح تشغيلية متقدمة

• ثبّت وسم إصدار: حيث المشروع مازال فمرحلة alpha، تثبيت وسم معروف كيقلّل من الأعطاب غير المتوقعة الناتجة عن تغيّر الـAPIs ولا المخططات.
• حافظ على Postgres: سجلّ الأحداث هو مصدر الحقيقة ديال عمليات التشغيل. دير نسخ احتياطية من قاعدة البيانات وسَيّرها accordingly.
• خلي بيانات الاعتماد فالبوابة: ما تتحايلش على البنية بنسخ أسرار التكامل طويلة الأمد للـsandboxes.
• استعمل الموافقات بوعي: خلّي ضوابط الإنسان داخل الحلقة مفعّلة فالإجراءات المدمّرة، خصوصاً ملي كيبدا التشغيل عبر Slack ولا الجداول الزمنية.
• اختار sandboxes حسب التشغيل: Daytona كيوفّر مساراً مُداراً، بينما CubeSandbox كيدعم التنفيذ المستضاف ذاتياً وبقاء البيانات فالمكان ديالها.
• شغّل فحوصات الأنواع بانتظام: العقود المشتركة كتمتد على بزاف ديال مساحات العمل، لذلك استعمل bun run typecheck من بعد التغييرات بين الحزم.
• راجع مسارات الإنتاج: التوجيه الكامل ديال النشر موجود تحت infra/self-host/، ومسار إصدار الحاويات غير القابلة للتغيير والإضافي موثّق فـdocs/operations/immutable-releases.md.
• فتّش فمسار الطلب: المستودع فيه رسم تفاعلي فـdocs/architecture/request-flow.html للدراسة المعمارية المعمّقة.

التكاملات وواجهات التسليم

بالإضافة لدعم Slack وGitHub الأصلي، المنصة كتعرض Gmail وLinear وNotion وHubSpot عبر موصلات. كيتكلف وسيط بالمصادقة عبر OAuth، وكتتشفّر الرموز فالجهة ديال الخادم. واجهات مساحة العمل كتشمل قاعدة المعرفة، وذاكرة الفريق، والمهارات، ودفاتر التشغيل، والأتمتة المبرمجة.

تكامل GitHub كيدعم المصادقة عبر App، واستنساخ المستودعات، وسير عمل طلبات الدمج. كيفما كان التكامل، استدعاءات الأدوات كتدوز من البوابة الموثوقة، وما كتعرّضش بيانات الاعتماد مباشرة لمحطة عمل agent.

اعتبارات الترخيص

يتم توزيع useAgent بموجب رخصة GNU AGPL v3.0-only. يمكن استعماله وتعديله واستضافته ذاتياً وفقاً لهاد الشروط. كاينة رخصة تجارية للاستعمال داخل منتجات احتكارية، أو منتجات OEM ولا white-label، أو التوزيع بلا التزامات AGPL، ولا لأي متطلبات أخرى متعلقة بالترخيص.

الخلاصة

كيجمع useAgent بين محركات متعددة للوكلاء، وتشغيلات دائمة مدعومة بـ Postgres، وبيئات Linux معزولة، وسياق تنظيمي، وتكاملات آمنة، والموافقات، والوثائق القابلة للتعديل، كاملين فـ منصة وحدة قابلة للاستضافة الذاتية. بدا محلياً باستعمال Bun وpgvector، وتحقق من monorepo باستعمال مدقق الأنواع ديالو، ومن بعد استعمل المسار الموثق للاستضافة الذاتية ملي تنقل لخادم Linux مخصص للإنتاج.