AgentX عمليًا 6: تقرير يومي في موعد ثابت

حتى الآن، كان وكيلك لا يعمل إلا حين يطلب منه أحد شيئًا. في الجزء 5 أعطيته مهمة من لوحة التحكم وتابعتها حتى النهاية.

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

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

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

• جدولة اسمها daily-report تعمل في الثامنة صباحًا بتوقيتك، من الاثنين إلى الجمعة.
• دليل على أنها تعمل: تقرير كتبه الوكيل في تشغيل تجريبي، تقرؤه دون انتظار الغد.
• سطر قيمة للمهمة، لتعرض لوحة التحكم سبب تشغيلها وتتوقف عن وسمها بـ look stale.

AgentX جزء من برنامج منتجات Noqta وما زال تجريبيًا. في هذا الإصدار يخطئ نموذج الجدولة في لوحة التحكم في المنطقة الزمنية (انظر الخطوة 2)، لذلك يعتمد هذا الدليل على الطرفية.

المتطلبات

• AgentX مع وكيل واحد يعمل، من الجزء 3.
• الإصدار 0.217.0 من AgentX أو أحدث. تحقق بالأمر agentx --version. للتحديث، أعد تشغيل أمر التثبيت من الجزء 2.
• الخدمة الخلفية تعمل (الأمر agentx daemon status يعرض running) ولوحة التحكم (agentx board serve)، كما في الجزء 5.
• طرفية ومحرر نصوص.

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

الخطوة 1: أعطِ الوكيل ما يكتب عنه التقرير

التقرير يحتاج إلى مصدر. الجدولة لا تفعل سوى إرسال رسالة إلى الوكيل في موعد ثابت، ويبقى على الوكيل أن يعرف أين يبحث. في هذا الدليل وضعنا سجل عمل صغيرًا في مجلد الوكيل نفسه، agents/assistant/work-log.md:

# Work log
 
## 2026-11-09
- Sent the quote to the bakery client (3 pages).
- Fixed the contact form: messages with an accent in the name were rejected.
- Still open: the hosting renewal invoice has not been paid.

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

الخطوة 2: اختر موعد التشغيل

يفهم AgentX المواعيد المكتوبة بالإنجليزية البسيطة. تحقق من طريقة قراءته لموعدك قبل حفظ أي شيء:

agentx schedule parse "weekdays at 8am"

  "weekdays at 8am"
    → 0 8 * * 1-5
    → At 08:00 AM, Monday through Friday

السطر الثاني هو الموعد نفسه مكتوبًا بصيغة cron، وهي الصيغة ذات الحقول الخمسة التي تستعملها أغلب أدوات الجدولة: الدقيقة، الساعة، يوم الشهر، الشهر، يوم الأسبوع. معنى 0 8 * * 1-5: الدقيقة 0، الساعة 8، أي يوم، أي شهر، من الاثنين إلى الجمعة.

عبارات أخرى تعمل: every day at 8am وevery monday at 10am وevery 15 minutes و1st of every month at noon. الإنجليزية وحدها مفهومة: العبارة tous les jours à 8h تعطي Couldn't parse.

لماذا لا نستعمل لوحة التحكم؟ في Settings › Schedules نموذج اسمه Add a schedule. في الإصدار 0.217.0 تقول تسميته إن الوقت "in the machine's time zone"، أي بتوقيت الجهاز، وكانت معاينته موافقة لذلك: كتبنا 0 9 * * 1 فعرضت الساعة 9:00 بتوقيت تونس. لكن النموذج يحفظ الجدولة بلا منطقة زمنية، فتشغّلها الخدمة الخلفية في الساعة 9:00 بتوقيت UTC، أي 10:00 عندنا. أما الطرفية فتحفظ المنطقة الزمنية مع الجدولة، فما تقرؤه هو ما يحدث فعلًا.

الخطوة 3: عاين الجدولة

اكتب الآن الأمر كاملًا، مع --dry-run حتى لا يُحفظ شيء بعد:

agentx schedule "weekdays at 8am" --agent assistant --id daily-report \
  --do "Read work-log.md. Write a short report of yesterday in three lines: what was done, what is still open, and one thing to do first today." \
  --dry-run

  ✓ would add cron daily-report
    Schedule: 0 8 * * 1-5  (At 08:00 AM, Monday through Friday, Africa/Tunis)
    Agent: assistant
    On error: log

وظيفة كل جزء:

• --agent هو الوكيل الذي ينفّذ العمل.
• --id هو اسم الجدولة. استعمل حروفًا إنجليزية صغيرة وأرقامًا و-. بدونه يختار AgentX اسمًا من الموعد واسم الوكيل (عندنا كان سيكون weekdays-assistant).
• --do هي الرسالة التي يتلقاها الوكيل كل مرة. حدّد بالضبط ما يقرؤه وشكل التقرير. "ثلاثة أسطر" تعطيك ثلاثة أسطر، و"لخّص" تعطيك أي شيء.
• --dry-run يعرض ما كان سيُحفظ ثم يتوقف.

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

agentx schedule "weekdays at 8am" --agent assistant --id daily-report \
  --do "..." --timezone Asia/Riyadh --dry-run

  ✓ would add cron daily-report
    Schedule: 0 8 * * 1-5  (At 08:00 AM, Monday through Friday, Asia/Riyadh)

استعمل الاسم الكامل للمنطقة، مثل Asia/Riyadh أو Africa/Tunis أو Europe/Paris. الاسم القصير مثل Tunis يُقبل هنا لكنه يفشل لاحقًا (انظر حل المشكلات).

الخطوة 4: احفظها

أعد تشغيل الأمر نفسه بدون --dry-run:

  ✓ Added cron daily-report
    Schedule: 0 8 * * 1-5  (At 08:00 AM, Monday through Friday, Africa/Tunis)
    Agent: assistant
    On error: log
    Daemon hot-reloaded.

Daemon hot-reloaded. تعني أن الخدمة الخلفية العاملة أخذت الجدولة الجديدة فورًا، دون حاجة إلى إعادة تشغيل. تُحفظ الجدولة في agentx.json تحت crons:

"daily-report": {
  "enabled": true,
  "schedule": "0 8 * * 1-5",
  "timezone": "Africa/Tunis",
  "agent": "assistant",
  "prompt": "Read work-log.md. Write a short report of yesterday in three lines: ...",
  "timeout": 600,
  "onError": ["log"]
}

اعرض جداولك للتحقق:

agentx schedule list

  ● daily-report                     0 8 * * 1-5    → assistant
      At 08:00 AM, Monday through Friday (Africa/Tunis)

النقطة الممتلئة ● تعني أنها مفعّلة، والجدولة المعطّلة تظهر بالدائرة الفارغة ○.

الخطوة 5: اختبرها دون انتظار الغد

لا يوجد في AgentX 0.217.0 زر "شغّل الآن" للجدولة. الطريقة السريعة لاختبارها هي نسخة تعمل كل دقيقتين، بالوكيل نفسه والرسالة نفسها:

agentx schedule "every 2 minutes" --agent assistant --id report-test \
  --do "Read work-log.md. Write a short report of yesterday in three lines: what was done, what is still open, and one thing to do first today."

  ✓ Added cron report-test
    Schedule: */2 * * * *  (Every 2 minutes, Africa/Tunis)
    Agent: assistant
    On error: log
    Daemon hot-reloaded.

انتظر الدقيقة الزوجية التالية. بدأ تشغيلنا الأول عند رأس الدقيقة وانتهى بعد 13 ثانية. ثم احذف النسخة فورًا، وإلا ستستمر في العمل كل دقيقتين وتستهلك حساب النموذج في كل مرة:

agentx schedule remove report-test

  ✓ report-test removed
    Daemon hot-reloaded.

الخطوة 6: اقرأ التقرير

يُحفظ كل تشغيل في ملف صغير داخل مجلد AgentX، تحت .agentx/cron/runs/<اسم الجدولة>/، ملف لكل تشغيل باسم وقت بدايته. افتح أحدثها:

ls -t .agentx/cron/runs/report-test | head -1

2026-11-10T09-08-00-002Z.json

التقرير موجود في "response"، و"success": true تعني أن التشغيل نجح. هذا ما كتبه وكيلنا:

**Yesterday (2026-11-09):**
- **Done:** Sent a 3-page quote to the bakery client; fixed the contact form bug that rejected names with accents.
- **Still open:** Hosting renewal invoice has not been paid.
- **First thing today:** Follow up on the hosting renewal invoice to avoid a service interruption.

كل ما فيه مأخوذ من سجل العمل في الخطوة 1، فتستطيع التحقق من كل سطر. إذا ظهر سطر غير موجود في المصدر، فاجعل الرسالة أكثر صرامة، مثل: "استعمل فقط ما في work-log.md".

لوحة التحكم تخبرك هل نجح التشغيل، لا بما قاله. افتح http://127.0.0.1:4202/mesh، واختر تبويب Operations، ثم اختر جدولتك تحت Routines:

الأسطر الثلاثة التي تهمك هي Last run وFailures in a row وNext fire. صفحة Activity تعرض كذلك كل تشغيل بعبارة from a job، لكن صفحة Open the run في الإصدار 0.217.0 تُظهر محادثة فارغة عليها HTTP 404، كما في الجزء 5. النص موجود في الملف.

لتصلك التقارير بدل أن تذهب إليها، يمكن للجدولة أن تنشر كل جواب في محادثة، على Telegram مثلًا، باستعمال --notify. هذا يحتاج إلى قناة متصلة، وهو موضوع الجزء 4 من السلسلة، لذلك لم نختبره هنا.

الخطوة 7: أضف للمهمة سطر قيمة

افتح Jobs من قائمة لوحة التحكم. كل مهمة متكررة تظهر هناك مع موعدها وآخر سبعة تشغيلات لها على شكل مربعات وحالتها. الجدولة الجديدة تُوسم بـ look stale حتى قبل أن تعمل:

Look stale تعني واحدًا من ثلاثة أمور: المهمة معطّلة منذ 14 يومًا أو أكثر، أو فشلت ثلاث مرات متتالية، أو ليس لها سطر قيمة. سطر القيمة يقول لماذا تعمل المهمة وأي رقم يثبت أنها تستحق. AgentX لا يقيس هذا الرقم، بل يعرضه ليسأل من يقرأ القائمة: "هل ما زالت هذه المهمة تستحق؟".

لا يوجد خيار لهذا في أمر الطرفية، فأضفه في agentx.json. افعل ذلك في الأخير: إعادة تشغيل agentx schedule بالمعرّف --id نفسه تستبدل المدخل كله وتحذف سطر القيمة. ابحث عن daily-report تحت crons وأضف كتلة value:

"daily-report": {
  "enabled": true,
  "schedule": "0 8 * * 1-5",
  "timezone": "Africa/Tunis",
  "agent": "assistant",
  "prompt": "Read work-log.md. ...",
  "timeout": 600,
  "onError": ["log"],
  "value": {
    "why": "Starts each weekday with what is done and what is still open",
    "metric": "Open items carried more than 2 days: 0"
  }
}

احفظ الملف، وستقرؤه الخدمة الخلفية من تلقاء نفسها. في صفحة Jobs تعرض daily-report الآن سطري Why وProves it، وتصبح حالتها on. أما عبارة no goal تحتها فهي ربط اختياري ومنفصل بهدف، ولا تجعل المهمة "stale".

تعرض Settings › Schedules المهام نفسها مع رسالتها وسطر قيمتها، وزر Delete لكل منها:

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

1. الأمر agentx schedule list يعرض ● daily-report مع Monday through Friday ومنطقتك الزمنية أنت بين القوسين.
2. اختفت report-test من القائمة.
3. في .agentx/cron/runs/report-test/ تشغيل واحد على الأقل فيه "success": true وتقرير تستطيع مقارنته بمصدرك.
4. صفحة Jobs في لوحة التحكم تعرض daily-report بحالة on، مع سطري Why وProves it، وnext in بعدد الساعات الصحيح.
5. في يوم العمل التالي بعد الثامنة صباحًا، يظهر أول ملف في .agentx/cron/runs/daily-report/.

حل المشكلات

Couldn't parse: "..." الموعد مكتوب بصيغة لا يعرفها AgentX. اكتبه بالإنجليزية وبإحدى الصيغ التي تقترحها الرسالة، مثل every morning at 9 أو daily at 9:30am. جرّبه أولًا بالأمر agentx schedule parse.

Agent "reporter" not found in agentx.json يليها Available: assistant. استعمل أحد المعرّفات في السطر الثاني.

الجدولة في القائمة لكنها لا تعمل أبدًا. ابحث في سجل الخدمة الخلفية عن Failed to schedule. رأينا Failed to schedule "tz-test": Invalid time zone specified: Tunis: قَبِل الأمر الاسم القصير للمنطقة، لكن الخدمة الخلفية رفضته. أعد تشغيل الأمر بالمعرّف --id نفسه وباسم كامل مثل Africa/Tunis. المدخل الجديد يستبدل القديم كله دون أي تنبيه، فأضف سطر القيمة من الخطوة 7 مرة أخرى بعد ذلك. تحقق كذلك من أن الخدمة الخلفية تعمل (agentx daemon status) وأن الجدولة تظهر بالعلامة ● (وإلا فنفّذ agentx schedule on daily-report).

عملت قبل موعدها أو بعده بساعة. للجدولة منطقة زمنية خاطئة، أو ليست لها منطقة. انظر إلى الاسم بين القوسين في agentx schedule list. الجدولة المنشأة من نموذج لوحة التحكم ليست لها منطقة زمنية وتعمل بتوقيت UTC. أنشئها من جديد من الطرفية.

النسخة التجريبية ما زالت تعمل. احذفها: agentx schedule remove report-test. لإيقاف جدولة مؤقتًا دون حذفها، استعمل agentx schedule off <الاسم> ثم agentx schedule on <الاسم>.

قُبِل الاسم وفيه مسافات أو حروف كبيرة. قَبِل الإصدار 0.217.0 المعرّف --id "Bad Name". استعمل مع ذلك حروفًا صغيرة و-، لأن بقية الأوامر ولوحة التحكم تشير إلى الجدولة بهذا الاسم.

فشل التشغيل. افتح أحدث ملف في .agentx/cron/runs/<الاسم>/: ستجد "success": false ومعها الخطأ. مشكلة تسجيل الدخول إلى النموذج تظهر بالطريقة نفسها كما في الجزء 3.

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

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

الخلاصة

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

إذا أردت تقارير كهذه مُعدّة ومتابَعة لنشاطك التجاري، تواصل معنا.