الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.
الـ schedule يشغّل الـ agent على تعبير cron، بدون أن يطلبه أحد: ملخص صباحي، تنظيف ليلي. تعرّف واحدًا بـ defineSchedule()، ومجلد الـ agent يلتقطها من schedules/، وstartSchedules() (أو سيرفر node) يشغّلها داخل العملية. الـ schedules حلّت محل CronTriggerAdapter (راجع الانتقال من الـ triggers).

عرّف schedule

أعطِ تعبير cron وواحدًا فقط من اثنين: prompt (نص يُرسَل للـ agent كـ turn جديد) أو run (دالة تكتبها أنت).
  • cron: خمسة حقول (minute hour day-of-month month day-of-week) أو @hourly أو @daily أو @weekly أو @monthly، ويُحسَب في timezone (اسم IANA، والافتراضي منطقة الجهاز الزمنية). إذا كان التعبير غير صالح، أو حدّدت prompt وrun معًا، أو ما حدّدت أي واحد منهما، defineSchedule() يرمي LOUSHO_SCHEDULE_INVALID مباشرة — لا عند أول firing. راجع الأخطاء.
  • run تستقبل { agent, firedAt, name }.
startSchedules(agent, schedules, { now?, setTimer?, onError?, keepAlive? }) يحتفظ بمؤقّت واحد لكل schedule. أي run يرمي خطأ يذهب إلى onError (الافتراضي: console.error) ولا يوقّف باقي الـ schedules أبدًا. والـ turn الخاص بـ prompt schedule إذا انتهى بأي finishReason غير 'stop' يُعتبَر run فاشلًا أيضًا: onError يستقبل خطأ LOUSHO_SCHEDULE_RUN_INCOMPLETE يذكر السبب، مثلًا 'awaiting-approval' (مع id الـ approval المعلّقة، وتبقى معلّقة إلى أن تحسمها بـ agent.approvals.resolve())، أو 'output-invalid' أو 'max-steps'. الـ schedule لا يتداخل مع نفسه: لو الـ firing السابق ما زال شغّالًا، يُتخطّى الإطلاق التالي ويُبلَّغ به onError. والـ fires التي فاتت أثناء تعليق العملية تُتخطّى بدل إعادة تشغيلها. now وsetTimer قابلان للحقن حتى لا تنام الاختبارات أبدًا. stop() يمسح المؤقّتات، فلا ينطلق شيء بعدها، ويرجع promise يُحسَم بعد أن تنتهي الـ runs الجارية فعلًا. يمكنك استدعاؤه بدون await. المؤقّتات unref’d: لا تُبقي العملية حيّة بمفردها أبدًا، فالسيرفر أو الاختبار ينتهي بشكل طبيعي. لذلك السكربت الذي لا يفعل شيئًا غير تشغيل الـ schedules سينتهي فورًا؛ مرّر keepAlive: true لهذه الحالة:

شغّل schedule الآن

fireSchedule(agent, schedule, { name?, firedAt?, sessionId? }) يطلق الـ schedule مرة واحدة، فورًا، تمامًا كما تفعل الـ tick: يستدعي run، أو يرسل prompt كـ turn (في sessionId إذا أعطيته، وهذا يحتاج agent له store؛ وافتراضيًا كل firing يعمل في session خاصة به، schedule-<name>-<fire time>، عندما يكون للـ agent ‏store، وschedule-<name> عندما يحدّد الـ schedule ‏sharedSession: true). ويرفض (reject) عندما يفشل الـ run، بما في ذلك بـ LOUSHO_SCHEDULE_RUN_INCOMPLETE، فهو مناسب لأمر “run now” في العمليات وللاختبارات. مع store للـ agent (ملف، SQLite، KV أو memoryStore())، كل firing يحجز أولًا اسم الـ schedule ووقت الإطلاق (بدقة الثانية) في store.checkpoints، فعدة نسخ (replicas) تشغّل startSchedules() على store واحد تطلق كل tick مرة واحدة فقط: النسخ التي تخسر الحجز تُحسَم بدون تشغيل أي شيء. وإطلاقان يدويان لنفس الـ schedule في نفس الثانية يُحسَبان tick واحدة أيضًا. على KV الحجز best effort عبر مواقع الـ edge (راجع التنفيذ المتين).

الـ prompt schedules والـ sessions

إطلاق الـ prompt schedule هو run من نوع agent.send(prompt, { sessionId })، وليس turn من نوع agent.session({ id }) (راجع نوعان من معرّف المحادثة). الـ id الخاص به schedule-<name>-<fire time> (وschedule-<name> مع sharedSession: true)، ومحادثته تُحفَظ في store.checkpoints الخاص بالـ agent، كـ checkpoint منتهية، إذا كان للـ agent واحد؛ وبدون checkpoint store يعمل الإطلاق بلا id ولا يحفظ شيئًا. GET /chat/<id> وagent.session({ id }).load() يقرآن من الـ session store، فيعرضان transcript فارغًا لـ id خاص بـ schedule. اقرأ تقرير الإطلاق من الـ checkpoint store بدلًا من ذلك، أو أكمله بـ agent.fork(id):

في مجلد الـ agent

resolveAgentDir() يرجعها في schedules (وأسماءها في manifest.schedules)؛ أما loadAgentDir() فلا يشغّلها. والمجلد الذي لا يحتوي schedules/ يُحمَّل كما كان تمامًا.

على سيرفر node

createDeployedServer(agent, { schedules }) — الـ helper الداخلي وراء السيرفر الذي يولّده lousho build للهدفين node-server وdocker — يشغّل الـ schedules عند بدء الاستماع ويوقفها عند الإغلاق. lousho build ./my-agent --target=node-server (أو docker) يبني مجلد الـ agent إلى سيرفر من هذا النوع، فتعمل schedules/ الخاصة به داخل العملية المنشورة (النشر). الـ triggers من نوع cron في ملف الـ spec ({ type: 'cron', cron, input, name?, timezone? }) تعمل على هذين الهدفين أيضًا: lousho build spec.yaml --target=node-server يحوّلها بنفس قواعد الـ Worker، والسيرفر المبني يشغّلها عند بدء الاستماع (timezone مدعوم؛ والـ trigger غير الصالح يفشل البناء بـ LOUSHO_SCHEDULE_INVALID). استدعاءات الـ model تتم داخل عملية السيرفر، فلازم تكون حزمة الـ provider مثبَّتة حيث يعمل. على Cloudflare Workers راجع القسم التالي.

في lousho dev

lousho dev ./my-agent يشغّل schedules المجلد، فينطلق cron وأنت تطوّر، والـ hot reload يوقّف الـ schedules القديمة قبل بدء الجديدة. التشغيل هو الوضع الافتراضي حتى يتصرّف dev مثل السيرفر المنشور؛ ولأن إطلاق الـ crons (وصرف استدعاءات الـ model) وأنت تعدّل غير مرغوب فيه غالبًا، --no-schedules يركّب الـ channels ولا يشغّل أي schedule. الـ triggers من نوع cron في ملف الـ spec تبدأ بنفس الطريقة (المعروض هنا spec من الإصدار v2؛ والصيغة { type: 'cron', cron, input, name? } من v1 تعمل أيضًا)، و--no-schedules لا يشغّل أيًّا منها كذلك:
أنواع الـ triggers التي لا يشغّلها lousho dev — webhook وchannel وagent — تُسجَّل في السجل مرة واحدة لكل تحميل (Agent Forge هو من يشغّلها).

على Cloudflare Workers

لا يحتوي الـ Worker على process طويلة العمر، فلا timers: Cloudflare تنادي الـ handler scheduled() في الـ Worker مرة لكل تعبير cron مدرَج تحت [triggers] crons في wrangler.toml. هدف cloudflare-worker يولّد الاثنين من triggers في ملف الـ spec الخاص بالـ agent — وفي مجلد الـ agent، من ملفات schedules/، وهي تتبع نفس القواعد أدناه:
lousho build يكتب التعبيرات بعد إزالة المكرر في [triggers] crons، وscheduled() في الـ Worker يشغّل كل trigger يساوي cron فيه التعبيرَ المستدعى، كـ turn للـ agent داخل ctx.waitUntil(). كل firing له session خاصة به، schedule-<name>-<fire time> (مثلًا schedule-weekly-report-2026-10-05T090000Z)، فالمهمة اليومية لا تعيد إرسال كل التقارير السابقة، ويمكن قراءة الـ run الخاص به من الـ checkpoints في KV عند ربط AGENT_CHECKPOINTS (راجع الـ prompt schedules والـ sessions؛ وليس عبر GET /chat/<id>). حدّد sharedSession: true على prompt schedule معرَّف بـ defineSchedule() لتحتفظ بـ session واحدة schedule-<name> بدلًا من ذلك؛ وعندها تكبر محادثتها مع كل firing. الـ run يتم داخل ctx.waitUntil()، بعد انتهاء عمر الطلب، فأعطِ الـ agent ‏store ‏(KVStore على AGENT_CHECKPOINTS) — الـ in-memory store يحفظ sessions الـ schedule فقط إلى أن يُعاد تدوير الـ isolate. إذا فشل trigger يُسجَّل بـ console.error (الاسم ورمز الخطأ) ولا يوقّف الباقي أبدًا، وscheduled() لا يرمي أبدًا. والـ turn الذي ينتهي بـ finishReason غير 'stop' يُسجَّل بنفس الطريقة، كـ LOUSHO_SCHEDULE_RUN_INCOMPLETE. الـ cron triggers في Cloudflare تختلف عن التي تعمل داخل العملية، لذلك يفشل البناء بـ LOUSHO_SCHEDULE_INVALID مع ذكر اسم الـ trigger، بدل أن يُخرج config يُنشَر ولا ينطلق أبدًا: التعبيرات بتوقيت UTC (لا timezone)، وخمسة حقول بالضبط (بلا ثوانٍ وبلا @daily)، ويجب أن يكون يوم الأسبوع * أو أسماء (MON-FRI)، لأن Cloudflare ترقّم الأيام من 1 إلى 7 بدءًا من الأحد. أصغر فاصل زمني ممكن دقيقة واحدة، وقد تبدأ Cloudflare الـ run متأخرةً بضع ثوانٍ. لو تريد ربط نقطة دخول Worker بنفسك، راجع Cloudflare Workers.