AgentX عمليًا 1: شغّل العرض التجريبي لـ AgentX في دقائق ومن دون حساب

AgentX منصة تشغّل وكلاء الذكاء الاصطناعي لفريق العمل وتتابع ما يفعلونه. تصل رسالة من أداة يستخدمها الفريق أصلًا، فيختار AgentX الوكيل المناسب ويشغّله ويسجّل ما حدث. وحين يكون جزء من العمل على حاسوب آخر، يربط AgentX الأجهزة ببعضها لتتبادل المهام.

هذا الجزء الأخير هو الأصعب تخيّلًا من مجرد الوصف، لذلك فأول ما تفعله مع AgentX أن تراه يعمل. يشغّل العرض التجريبي ثلاث خدمات AgentX خلفية على جهازك، ويربطها في شبكة صغيرة، ثم يعرض سيناريو واحدًا: عميل يبلّغ عن عطل في صفحة الدفع، فيحيل وكيل الدعم إصلاح الكود إلى وكيل هندسي على جهاز آخر، ثم تعود النتيجة.

هذا هو الجزء الأول من سلسلة AgentX عمليًا، وهي أدلة قصيرة يُنجز كل جزء منها شيئًا واحدًا. والشيء الواحد هنا هو العرض التجريبي.

ما الذي ستحصل عليه في النهاية

• ثلاث خدمات AgentX خلفية تعمل على جهازك، كل منها تمثّل جهازًا مختلفًا: laptop-paris وvps-nyc وpi-office.
• لوحة تحكم AgentX مفتوحة في متصفحك وتعرض الأجهزة الثلاثة.
• مهمة واحدة انتقلت من الوكيل @cx على laptop-paris إلى الوكيل @builder على vps-nyc ثم عادت.
• سجل تلك المهمة، تقرؤه بأمر واحد.

ما الحقيقي وما غير الحقيقي. الخدمات الخلفية، والاتصالات الشبكية بينها، والمصادقة، والسجلات كلها حقيقية. الشيء الوحيد المكتوب مسبقًا هو ردود النموذج، فلا يُستدعى أي نموذج ذكاء اصطناعي مدفوع، ولا تحتاج إلى حساب أو مفتاح API. ولا يقترب العرض من أي وكلاء أو بيانات اعتماد حقيقية قد تكون لديك.

AgentX جزء من برنامج منتجات نقطة، وما يزال تجريبيًا. والعرض التجريبي أكثر الأماكن أمانًا للتعرّف عليه: يعمل بالكامل على جهازك وينظّف ما خلّفه عند الإغلاق.

المتطلبات

• Node.js بإصدار 22.19 أو أحدث، حتى 26. يرفض AgentX العمل على غير ذلك. شُغّل هذا الدليل على Node.js 22.22.0.
• طرفية (Terminal على macOS، أو shell على Linux، أو PowerShell أو WSL على Windows).
• متصفح لعرض لوحة التحكم.
• نحو دقيقتين للتشغيل الأول، لأن npx ينزّل حزمة AgentX. على جهازنا استغرق التشغيل الأول 69 ثانية من كتابة الأمر حتى نهاية السيناريو.

لا تحتاج إلى Git ولا Docker ولا حساب ولا مفتاح API ولا نسخة من الكود المصدري.

الخطوة 1: تحقّق من إصدار Node.js

في الطرفية، شغّل:

node --version

المخرَج عندنا:

v22.22.0

إذا كان الرقم أقل من v22.19 أو أعلى من v26، فثبّت Node.js 22 من nodejs.org وأعد تشغيل الأمر.

الخطوة 2: شغّل العرض التجريبي

اختر مجلدًا فارغًا، لأن العرض يكتب ملفات عمله في مجلد اسمه .agentx-demo حيثما شغّلته. ثم شغّل:

npx agentix-cli demo

اسم الحزمة agentix-cli، والأمر الذي تثبّته هو agentx. إذا سألك npx بالرسالة Need to install the following packages: agentix-cli فأجب بـ y.

لتحصل على ما يعرضه هذا الدليل بالضبط، ثبّت الإصدار الذي اختبرناه:

npx agentix-cli@0.114.1 demo

يصدر AgentX إصدارات جديدة كثيرًا، فقد تختلف صياغة سطر هنا أو هناك في إصدار أحدث. أما الخطوات فتبقى نفسها.

على خادم أو من دون متصفح، أضف --no-open. عندها يطبع العرض عنوان لوحة التحكم وتفتحه أنت.

الخطوة 3: اقرأ أسطر الإقلاع

بعد التنزيل، يطبع العرض لافتة قصيرة ويشغّل الخدمات الثلاث. هذا تشغيلنا بعد حذف تحذيرات تنزيل npm. شغّلناه مع --base-port 19021، لذا فأرقام المنافذ عندنا من 19021 إلى 19023 ثم 19031. أما عندك فستكون من 18921 إلى 18923 ثم 18931 ما لم تغيّر المنفذ الأساسي.

  agentx demo — one message, three machines (simulated on loopback)
  Canned model responses. Real daemons, real A2A mesh, real ledger.
  Run `agentx setup` to wire real agents.
 
  Startup limit: 60s per step (default for load 3.8 on 8 CPUs)
  ▸ laptop-paris starting on 127.0.0.1:19021 (log: .../.agentx-demo/node-a/daemon.log)
  ▸ vps-nyc starting on 127.0.0.1:19022 (log: .../.agentx-demo/node-b/daemon.log)
  ▸ pi-office starting on 127.0.0.1:19023 (log: .../.agentx-demo/node-c/daemon.log)
  ✓ three daemons up
  ✓ dashboard up
  ✓ A2A mesh healthy — agent cards exchanged across three nodes
 
  Dashboard:   http://127.0.0.1:19031/live  (all three nodes via the mesh)
  Daemon APIs: 127.0.0.1:19021 · 127.0.0.1:19022 · 127.0.0.1:19023

معنى كل جزء:

• ثلاث خدمات خلفية (daemons). الخدمة الخلفية هي ما يعمل به AgentX في الخلفية. كل واحدة هنا تمثّل جهازًا مستقلًا، ولها مجلدها الخاص (node-a وnode-b وnode-c) بإعداداتها وسجلّها.
• لوحة التحكم (Dashboard). واجهة المتصفح، وتعمل على المنفذ الأساسي زائد 10.
• A2A mesh healthy. تعني A2A الاتصال من وكيل إلى وكيل. الأجهزة المتصلة تشكّل شبكة (mesh)، وقد نشر كل جهاز بطاقة تصف وكلاءه. هذا هو السطر المهم: الأجهزة الثلاثة يصل بعضها إلى بعض.
• Startup limit. المدة المسموح بها لكل خطوة إقلاع قبل أن يتوقف العرض. القيمة الافتراضية 60 ثانية، وتطول على الجهاز المشغول.

الخطوة 4: تابع السيناريو في الطرفية

مباشرة بعد الإقلاع، يعرض العرض سيناريوه. هذا تشغيلنا مختصرًا:

  ── Scenario: red pipeline, cross-node fix ──
 
  You → @cx (laptop-paris)
  [demo] Customer reports checkout is broken and CI is red on demo/shop. Handle it.
 
  @cx (laptop-paris)
  Checkout failure traced to the red pipeline on demo/shop. This needs a code fix — delegating to @builder on the vps-nyc node over the mesh. I'll report back on this thread.
 
  ⇄ mesh hop: laptop-paris → vps-nyc (A2A /task)
 
  @builder (vps-nyc)
  Fixed. checkout.test.ts assumed the legacy crypto.webcrypto import — patched for Node 22, suite green locally. Opened MR !47 on demo/shop; pipeline is green. Handing back to @cx.
 
  (...)
 
  Inspect the run: http://127.0.0.1:19031/live  ·  ledger rows on each node record every dispatch
 
  Daemons stay up — browse the dashboards. Press Enter to replay, Ctrl-C to exit.

اقرأه كسباق تتابع:

1. ترسل رسالة إلى @cx، وكيل خدمة العملاء على laptop-paris.
2. يقرّر @cx أن المشكلة في الكود وليست سؤال دعم، فيحيلها إلى @builder.
3. سطر mesh hop هو لحظة الإحالة: طلب HTTP حقيقي من خدمة خلفية إلى أخرى، مصادَق عليه برمز تتشاركه الأجهزة الثلاثة.
4. يبلّغ @builder على vps-nyc عن الإصلاح ويعيد المهمة.
5. يغلق @cx الحلقة مع العميل (السطر الذي اختصرناه بـ (...)).

صياغة كل رد مكتوبة مسبقًا، أما التوجيه فلا: أرسل @cx المهمة فعلًا عبر الشبكة، واستلمها @builder فعلًا على خدمة خلفية أخرى.

الخطوة 5: افتح لوحة التحكم

فتح متصفحك لوحة التحكم على تبويب Live. وإن لم يفعل، فافتح عنوان Dashboard: من الخطوة 3.

يعرض Live كل جهاز في الشبكة والوكلاء الذين عليه. يجب أن يظهر 3/3 machines وثلاثة وكلاء. لدى @cx و@builder نشاط خلال آخر 24 ساعة، أما @scout على pi-office فيظهر عليه not used yet لأن السيناريو لا يحتاج إليه.

افتح الآن Activity من الشريط العلوي.

يرسم Activity كل تشغيل على خط زمني، بمسار لكل وكيل. تتناوب الأشرطة بين cx وbuilder لأن المهمة ذهبت من أحدهما إلى الآخر ثم عادت. وكلما أعدت تشغيل السيناريو ظهرت أشرطة جديدة.

ثم افتح Monitor.

Monitor هي صفحة العمل الذي يحتاج إلى إنسان. وفي العرض تقول Nothing needs you، وهذا صحيح: انتهى السيناريو من دون أن يحتاج أحد إلى اتخاذ قرار. العرض جولة في التوجيه وليس نسخة ممتلئة من شركة حقيقية، لذا تبقى بعض الصفحات فارغة.

الخطوة 6: أعد التشغيل ثم أوقفه

عُد إلى الطرفية:

• اضغط Enter لتشغيل السيناريو مرة أخرى. جرّبنا ذلك، فجرى سباق التتابع نفسه مرة ثانية وظهرت أشرطة جديدة على خط Activity الزمني.
• اضغط Ctrl-C للإيقاف. تتوقف الخدمات الثلاث ولوحة التحكم، وتُحرَّر المنافذ، ويُحذف مجلد .agentx-demo.

إذا أردت تشغيلًا واحدًا ثم توقفًا تلقائيًا، فابدأ العرض مع --once:

npx agentix-cli demo --once

الخطوة 7 (اختيارية): اقرأ سجل ما حدث

تُكتب كل إحالة في سجل يسمّيه AgentX ledger، بل إن @cx يذكر ذلك في رده الأخير. ولكي تقرأه يجب أن يبقى السجل بعد الإيقاف، فشغّل العرض مرة واحدة مع --keep:

npx agentix-cli demo --once --keep

ثم ادخل مجلد الجهاز الأول واطلب ملخصًا:

cd .agentx-demo/node-a
npx agentix-cli ledger stats

المخرَج عندنا بعد سيناريو واحد:

Events by source
source  n
------  -
mesh    2
 
Decisions: 2
outcome     n
----------  -
dispatched  2
 
Divergences: 0
  (no rows)
 
In-flight (dispatched, no resolution): 0

والأحداث نفسها، الأحدث أولًا:

npx agentix-cli ledger events -n 4

at                   source  project  subject        intent
-------------------  ------  -------  -------------  ---------
2026-10-06 09:09:21  mesh    -        mesh:agent:cx  mesh.task
2026-10-06 09:09:15  mesh    -        mesh:agent:cx  mesh.task

وصل حدثان إلى @cx على laptop-paris عبر الشبكة: رسالتك الأولى، وتقرير @builder العائد. كلاهما أُحيل، ولم يبقَ شيء معلّقًا. هذا هو الجانب من AgentX الذي لا يظهر في نافذة محادثة: بعد انتهاء العمل، ترى أين ذهبت كل قطعة منه.

حين تنتهي، احذف مجلد .agentx-demo.

خيارات مفيدة

شُغّلت كلها لهذا الدليل على الإصدار 0.114.1.

تحقّق من النجاح

1. طبعت الطرفية A2A mesh healthy.
2. طبع السيناريو سطر mesh hop: laptop-paris → vps-nyc.
3. يعرض تبويب Live القيمة 3/3 machines.
4. يعرض تبويب Activity أشرطة في مساري cx وbuilder كليهما.

إذا تحققت الأربعة، فقد نجح العرض، ورأيت الفكرة الأساسية لـ AgentX: رسالة واحدة توجَّه إلى الوكيل المناسب عبر الأجهزة، مع سجل لكل خطوة.

حل المشكلات

يبدو التشغيل الأول عالقًا. إنه ينزّل الحزمة. انتظر دقيقتين قبل أي شيء آخر. في المرات التالية يبدأ خلال ثوانٍ.

عرض آخر يعمل في مكان آخر. أوقفه أولًا. اختبرنا تشغيل عرض ثانٍ على المنافذ نفسها بينما الأول يعمل: لم يفشل. طبع three daemons up وعرض سيناريوه على الخدمات الخلفية للعرض الأول، وظهرت التشغيلات الإضافية في تبويب Activity للعرض الأول. إذا رأيت تشغيلات أكثر مما شغّلت، فهذا هو السبب. أوقف العرض الآخر بـ Ctrl-C، أو امنح هذا العرض منافذه الخاصة:

npx agentix-cli demo --base-port 19021

عندها تكون لوحة التحكم على المنفذ 19031.

AgentX needs Node.js 22.19 or newer, up to 26. إصدار Node.js لديك أقدم أو أحدث من المطلوب. ثبّت Node.js 22 وتحقق بـ node --version. (هذه الرسالة منقولة من الكود المصدري لـ AgentX، ولم نُعِد إنتاجها لهذا الدليل.)

لم يُفتح المتصفح. افتح عنوان Dashboard: المطبوع في الطرفية. وعلى الخادم، ابدأ العرض مع --no-open وافتح العنوان من ذلك الجهاز.

تنتهي مهلة خطوة إقلاع على جهاز بطيء أو مشغول. امنحها وقتًا أطول بـ --startup-timeout 120.

لا يعرض ledger stats أي صفوف. أنت في المجلد الخطأ، أو لم يُشغَّل العرض مع --keep. يوجد السجل داخل .agentx-demo/node-a، ومن دون --keep يُحذف هذا المجلد عند الخروج.

شاهده

يعرض أول فيديو من سلسلة Learn AgentX العرضَ التجريبي نفسه: youtu.be/J_QC6QCsSBs.

الجزء التالي من السلسلة

يثبّت الجزء الثاني AgentX فعليًا ويتحقق من التثبيت بالأمر agentx doctor. وإلى ذلك الحين، توثيق AgentX موجود على github.com/anis-marrouchi/agentx، ومقالنا عن كيف تعمل أنظمة المعرفة متعددة الوكلاء في الإنتاج يشرح لماذا بنيناه.

الخلاصة

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

إذا أردت وكلاء كهؤلاء يعملون على أدوات فريقك، مع توجيه وسجل نتولّاهما عنك، تحدّث إلينا.