الكتابات/tutorial/2026/11
● Tutorial17 نوفمبر 2026·10 دقيقة

AgentX عمليًا 7: ابنِ أول سير عمل لك

ابنِ سير عمل في AgentX من ثلاث خطوات يحوّل ملاحظات اجتماع إلى قائمة مهام: أنشئه من قالب، وصحّح السطر الذي يكتبه القالب خطأً، وشغّله من الطرفية، واقرأ الإجابة، وافتحه على لوحة الرسم. كل أمر وكل مخرَج في هذا الدليل شُغّل فعلًا على الإصدار 0.227.1 من AgentX.

حتى الآن، كان كل عمل أعطيته لوكيلك رسالة واحدة: سؤال في الجزء 5، وتقرير في موعد ثابت في الجزء 6.

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

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

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

  • سير عمل اسمه meeting-actions من ثلاث خطوات: start (أنت تبدؤه)، وreply (وكيل يقرأ الملاحظات)، وdone.
  • تشغيل واحد له، بإجابة يمكنك مطابقتها سطرًا بسطر مع الملاحظات التي أعطيتها.
  • سير العمل نفسه مفتوحًا على لوحة الرسم (canvas)، وهي رسم الخطوات في لوحة التحكم، حيث يمكنك تعديله دون فتح الملف.

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

المتطلبات

  • AgentX مع وكيل واحد يعمل، من الجزء 3.
  • AgentX 0.227.1 أو أحدث. تحقّق بـ agentx --version. للتحديث، أعد تشغيل أمر التثبيت من الجزء 2.
  • لوحة التحكم (agentx board serve)، كما في الجزء 5.
  • طرفية ومحرر نصوص.

كيف شغّلناه. كما في الأجزاء السابقة، شغّلنا كل شيء في مجلد منزلي نظيف ومنفصل، على جهاز Mac يشغّل نسخة أخرى من AgentX، والخدمة الخلفية (daemon) على المنفذ 19021 ولوحة التحكم على 19031. عندك ستظهر القيم الافتراضية، 18800 و4202. ولأن خدمتنا لم تكن على المنفذ الافتراضي، يحمل أمر run عندنا --daemon http://127.0.0.1:19021. في التثبيت العادي، احذف هذا الجزء. وكيلنا كان وكيل البداية Assistant (assistant)؛ ضع معرّف وكيلك مكان assistant أينما ظهر.

الخطوة 1: فعّل سير العمل

سير العمل معطّل في التثبيت الجديد. افتح agentx.json في مجلد AgentX وأضف كتلة workflows في المستوى الأعلى:

"workflows": {
  "enabled": true
}

أضفناها قبل تشغيل الخدمة الخلفية. إن كانت خدمتك تعمل، أوقفها ثم شغّلها من جديد لتقرأ التغيير. عند التشغيل يقول سجل الخدمة:

[agentx]   Workflows: enabled (1 definition loaded from .agentx/workflows, editor=edit, cron=0, hook=0, poll=0)

الخطوة 2: ابدأ من قالب

لا تحتاج إلى كتابة سير عمل من الصفر. في AgentX قوالب جاهزة:

agentx workflow templates
  linear               Linear
                       Trigger → Agent → End. Smallest workflow that runs.
  branching            Branching
                       Classify, then route on the result via a branch node.
  extract              Structured extraction
                       Pull typed fields from free-form text via extract.structured.
  retry                Retry + fallback
                       Per-node retry policy with a branch fallback path.
  release-follow-up    Release follow-up
                       Deploy, check it is live, tell the client (with your approval). Followed to the end; one summary for you.

Linear هو المناسب لأول سير عمل. أنشئ سير عملك منه، مع وكيلك وعنوان:

agentx workflow init meeting-actions --agent assistant --title "Meeting notes to actions"
  ✓ scaffolded /private/tmp/axhowto07.QblZ/work/.agentx/workflows/meeting-actions.yaml
    template: linear
 
  Next:
    1. edit /private/tmp/axhowto07.QblZ/work/.agentx/workflows/meeting-actions.yaml
    2. agentx workflow validate /private/tmp/axhowto07.QblZ/work/.agentx/workflows/meeting-actions.yaml
    3. agentx workflow run meeting-actions --watch

meeting-actions هو معرّف سير العمل، أي اسمه القصير: حروف لاتينية صغيرة وأرقام و- و_. يُنشأ الملف في .agentx/workflows/ داخل مجلد AgentX، وهناك تبحث الخدمة الخلفية عن سير العمل.

الخطوة 3: اكتب ما يفعله الوكيل، وصحّح سطر الإدخال

افتح .agentx/workflows/meeting-actions.yaml. بدون تعليقاته، يبدو القالب هكذا:

id: meeting-actions
version: 2
title: Meeting notes to actions
 
flow:
  - start
  - reply
  - done
 
nodes:
  - id: start
    type: trigger.manual
    config: {}
 
  - id: reply
    type: agent
    config:
      agentId: assistant
      prompt: |
        The user said: {{trigger.payload.text}}
        Reply concisely.
 
  - id: done
    type: end
    config:
      status: completed

اقرأه من الأعلى:

  • flow يسرد الخطوات بترتيب تشغيلها. كل اسم فيه هو id لخطوة تحت nodes.
  • start خطوة من نوع trigger.manual: يبدأ سير العمل حين تبدؤه أنت.
  • reply خطوة من نوع agent: ترسل prompt إلى الوكيل المذكور في agentId وتحتفظ بإجابته.
  • done خطوة من نوع end: ينتهي التشغيل بحالة completed.

غيّر نص الطلب (prompt) ليعرف الوكيل عمله. كن دقيقًا في شكل الإجابة التي تريدها:

      prompt: |
        Here are notes from a meeting:
        {{start.text}}
        List the action items as a numbered list. For each one, give
        who does it and by when, if the notes say so. Nothing else.

انظر إلى السطر الثاني. كتب القالب {{trigger.payload.text}}، وغيّرناه إلى {{start.text}}. هذا مهم. أي {{...}} في نص الطلب يُملأ بما أنتجته الخطوات السابقة، ونتيجة كل خطوة تُحفظ تحت معرّف تلك الخطوة. النص الذي تعطيه لسير العمل يُحفظ تحت start، لذلك يجده {{start.text}}. لا شيء يُحفظ تحت trigger، فيُستبدل سطر القالب في الإصدار 0.227.1 بلا شيء، دون أي رسالة خطأ. أول تشغيل لنا، بسطر القالب، أجاب:

No meeting notes were included in your message. Please paste the notes and I'll extract the action items.

القاعدة التي تحفظها: {{<معرّف الخطوة>.<الحقل>}}. إن كانت خطوة البداية اسمها start فالنص هو {{start.text}}، وخطوة لاحقة تقرأ إجابة الوكيل بـ {{reply.reply}}.

تحقّق من الملف قبل استعماله:

agentx workflow validate .agentx/workflows/meeting-actions.yaml
  ✓ meeting-actions — valid

valid تعني أن الملف بالشكل الصحيح. لا تتحقق من أن {{...}} يشير إلى خطوة موجودة: ملفنا بالسطر الخاطئ كان صالحًا أيضًا.

الخطوة 4: شغّله

أعطِ سير العمل مدخله بصيغة JSON عبر --input. اسم الحقل، text، هو الذي يقرؤه نص الطلب في {{start.text}}:

agentx workflow run meeting-actions --watch --input '{"text":"Weekly call, 16 Nov. Sara will send the new price list to the shop by Thursday. Omar checks the delivery dates with the supplier. We meet again next Monday."}'
  ✓ run started: 4b278bdc-8b29-4327-ab34-5ebc58050352
  in-flight (node)
  ok    (node)    0ms
 
  run finished: completed
  full traces: http://127.0.0.1:19021/traces?workflowRunId=4b278bdc-8b29-4327-ab34-5ebc58050352

--watch يتابع التشغيل حتى ينتهي. السطر الذي يهمّ هو run finished: completed. في هذا الإصدار تُظهر أسطر الخطوات (node) بدل أسماء الخطوات، والمدة المعروضة ليست مدة الوكيل: الوكيل نفسه أخذ بضع ثوانٍ.

غيّرنا نص الطلب والخدمة الخلفية تعمل، واستعمل التشغيل الثاني النص الجديد. لم نُعِد تشغيل أي شيء.

لرؤية كل تشغيلات سير العمل:

agentx workflow runs meeting-actions
  4b278bdc  meeting-actions  ∅  completed
    entity:   manual:manual-mwkgufzr
    home:     mac
    updated:  2026-11-17T09:04:41.930Z
    last:     done  (ok)
  940939aa  meeting-actions  ∅  completed
    entity:   manual:manual-mwkgt2lf
    home:     mac
    updated:  2026-11-17T09:03:25.010Z
    last:     done  (ok)
 
  2 runs.

التشغيل الأقدم، 940939aa، هو الذي كان بسطر القالب من الخطوة 3، وقد اكتمل هو أيضًا. التشغيل الذي ينتهي بنجاح قد يحمل إجابة خاطئة رغم ذلك، ولهذا تقرأ الخطوة 5 الإجابة.

الخطوة 5: اقرأ الإجابة

الطرفية تخبرك أن التشغيل نجح، لا ما كتبه الوكيل. كل تشغيل يُحفظ في ملف داخل .agentx/workflows/_runs/، سطر لكل خطوة، وإجابة الوكيل في السطر الأخير. هذا الأمر يقرؤها من أحدث تشغيل (Node موجود على حاسوبك أصلًا، لأن AgentX يحتاجه):

node -e 'const fs=require("fs"),d=".agentx/workflows/_runs/";const f=fs.readdirSync(d).map(n=>d+n).sort((a,b)=>fs.statSync(b).mtimeMs-fs.statSync(a).mtimeMs)[0];const last=JSON.parse(fs.readFileSync(f,"utf8").trim().split("\n").pop());console.log(last.context.reply.reply)'
1. Sara sends the new price list to the shop — by Thursday.
2. Omar checks delivery dates with the supplier — no deadline given.
3. Team meets again — next Monday (23 Nov).

قارنها بالملاحظات: ثلاث مهام، والأسماء صحيحة، و«no deadline given» حيث لم تذكر الملاحظات موعدًا. هذه فائدة نص الطلب الدقيق. وreply.reply يتبع قاعدة الخطوة 3 نفسها: معرّف الخطوة ثم الحقل.

الخطوة 6: شاهده في لوحة التحكم

افتح لوحة التحكم (http://127.0.0.1:4202) واختر Workflows من القائمة، تحت Automation. اختر اسم سير العمل لتفتح آخر تشغيل له:

صفحة Workflows في الـHub: سير العمل Meeting notes to actions بحالة Done ومفتاح On، وStarted by hand وAssistant، ومربعان أخضران لتشغيلين، وآخر تشغيل مفتوح وخطوته Reply مكتملة

يخبرك السطر بما يبدأ سير العمل (Started by hand)، وبالوكيل الذي يعمل فيه، ومربع لكل تشغيل: أخضر للمكتمل، وأحمر للفاشل. التشغيل المفتوح تحته يسرد كل خطوة بعلامة صح. Run again يعيد تشغيله بالمدخل نفسه. All 2 runs يفتح السجل الكامل، وفيه يظهر من مخرَج كل خطوة سطرها الأول فقط؛ الإجابة الكاملة في ملف الخطوة 5.

اختر Open in the editor، ثم مربع reply:

محرر سير العمل: خطوة reply محددة، ووكيلها Assistant ونص طلبها مع start.text في القائمة الجانبية، والمربعات الثلاثة start وreply وdone متصلة بأسهم على لوحة الرسم

هذا هو الملف نفسه، مرسومًا على شكل مربعات. تعرض القائمة الجانبية الخطوة المحددة: وكيلها ونص طلبها، وفيه {{start.text}}. وفوق نص الطلب يذكّر المحرر بقاعدة الخطوة 3: «Supports {{nodeId.path}} variables from upstream context». الحالة بجانب العنوان تقول saved. بحسب توثيق AgentX، تعديل خطوة هنا ثم اختيار Save يكتب هذا التعديل وحده في الملف؛ في هذا الدليل اكتفينا بالنظر ولم نحفظ من المحرر.

تحقق من أنه يعمل

  1. agentx workflow validate .agentx/workflows/meeting-actions.yaml يطبع valid.
  2. agentx workflow run ... --watch ينتهي بـ run finished: completed.
  3. إجابة الخطوة 5 تسرد المهام من ملاحظاتك أنت. إن قالت إنه لم تُرفق ملاحظات، فارجع إلى الخطوة 3.
  4. Workflows في لوحة التحكم تعرض Meeting notes to actions بحالة Done وOn، ومربعًا أخضر لكل تشغيل.

حل المشكلات

الوكيل يجيب وكأنه لم يتلقَّ نصًا. نص الطلب يقرأ حقلًا غير موجود، فيُستبدل بلا شيء. استعمل {{<معرّف الخطوة>.<الحقل>}}: مع القالب، هذا {{start.text}} وليس {{trigger.payload.text}}. وتأكد أن الحقل في --input يحمل الاسم نفسه (text).

request to daemon failed: fetch failed. الخدمة الخلفية لا تعمل، أو ليست على المنفذ الافتراضي. تحقق بـ agentx daemon status. إن كانت خدمتك على منفذ آخر، أضف --daemon http://127.0.0.1:<المنفذ> إلى agentx workflow run. هذا الأمر لا يقرأ المنفذ من agentx.json.

سير العمل لا يعمل، أو لا تظهر تشغيلات في لوحة التحكم. تحقق من "workflows": { "enabled": true } في agentx.json ومن أن الملف في .agentx/workflows/. ثم أوقف الخدمة الخلفية وشغّلها من جديد.

أي معرّف وكيل أستعمل؟ يجب أن يكون agentId أحد وكلائك. agentx agent list يعرضهم؛ عندنا: assistant — Assistant (claude-code).

agentx workflow list يقول trigger: ?. في الإصدار 0.227.1 يقول ذلك لسير العمل هذا أيضًا، مع أن البدء يعمل. لوحة التحكم تقول Started by hand، وهذا هو الصحيح.

التالي في السلسلة

الجزء التالي يشرح تشغيل Claude Code وكيلًا داخل AgentX. ومن هنا يمكن لسير العمل أن يكبر: خطوة ترسل القائمة إلى محادثة، أو اختيار بين طريقين، أو توقف ينتظر موافقتك. وضع وكيلك على Telegram هو الجزء 4 ويصدر منفصلًا. إلى ذلك الحين، توثيق AgentX موجود على github.com/anis-marrouchi/agentx.

الخلاصة

بنيت سير عمل من ثلاث خطوات: خطوة تبدؤها أنت، وخطوة يعمل فيها وكيل، وخطوة تُنهي التشغيل. أنشأته من قالب، وصحّحت السطر الذي كان سيخفي ملاحظاتك عن الوكيل، وشغّلته بمدخل حقيقي، وقرأت الإجابة وطابقتها مع المصدر، ثم فتحت سير العمل نفسه على لوحة الرسم. كل سير عمل أكبر يُبنى بالطريقة نفسها: خطوة بعد خطوة، وكل خطوة تقرأ ما قبلها بمعرّفها.

إن أردت سير عمل كهذا لشركتك، تحدّث إلينا.

أرسل لنا مشروعك

نردّ خلال يوم عمل واحد.