feat: implement scheduling functionality for AgentflowV2

[prd-hoang-doan]

Ticket:

Flowise Roadmap

Overview

Adds first-class scheduled execution for Agentflows, including UI inputs for schedule configuration and a backend scheduler that can run via BullMQ (queue mode) or an in-process timer (non-queue mode).

agentflow-schedule.mov

Changes

• Introduces schedule configuration inputs on the Agentflow Start node (cron + visual picker) and renders new picker controls in the canvas UI.
• Adds server-side schedule persistence (new entities + DB migrations) plus cron/visual-picker validation and schedule upsert/disable hooks on chatflow save/update/delete.
• Implements schedule execution via new ScheduleBeat (sync + non-queue timer) and ScheduleQueue (BullMQ repeatable jobs), and wires the queue into QueueManager/worker startup.

Database

schedule_record

Column	Type	Nullable	Default	Description
id	uuid	No	uuid_generate_v4()	Primary key
triggerType	varchar(32)	No	-	Type of trigger (AGENTFLOW, DOCUMENT_STORE)
targetId	varchar	No	-	Target entity id (chatflowId / documentStoreId)
nodeId	text	Yes	-	Optional node identifier
cronExpression	text	No	-	Cron schedule expression
timezone	varchar(64)	No	UTC	Schedule timezone
enabled	boolean	No	true	Enable / disable schedule
defaultInput	text	Yes	-	Default input payload
lastRunAt	timestamp	Yes	-	Last execution time
nextRunAt	timestamp	Yes	-	Next planned execution time
workspaceId	varchar	No	-	Workspace identifier
createdDate	timestamp	No	now()	Created timestamp
updatedDate	timestamp	No	now()	Updated timestamp

schedule_trigger_log

Column	Type	Nullable	Default	Description
id	uuid	No	uuid_generate_v4()	Primary key
scheduleRecordId	varchar	No	-	Related schedule record id
triggerType	varchar(32)	No	-	Trigger type
targetId	varchar	No	-	Target entity id (chatflowId / documentStoreId)
executionId	varchar	Yes	-	Execution identifier
status	varchar(32)	No	-	Trigger result status
error	text	Yes	-	Error message if failed
elapsedTimeMs	integer	Yes	-	Execution duration
scheduledAt	timestamp	No	-	Scheduled execution time
workspaceId	varchar	No	-	Workspace identifier
createdDate	timestamp	No	now()	Created timestamp

Notes

• triggerType is introduced for future extensibility if more schedulable targets are added.
• schedule_trigger_log is separated from schedule_record to keep execution history scalable.
• timezone defaults to UTC for predictable cron behavior.

Recording Demo:

Youtube: https://youtu.be/MZ1ws7XqsBg

---

This PR includes a new migration for the scheduling entities. Please take a look when you have time, and feel free to share any feedback if changes are needed.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a robust scheduling system for Agentflows, enabling users to define recurring execution times directly within the Agentflow Start node. It provides a user-friendly interface for setting schedules via cron expressions or a visual picker, backed by a resilient backend that persists these configurations and manages their execution through either a message queue or an in-process timer. This enhancement significantly expands the automation capabilities of Agentflows, allowing for time-based triggers without manual intervention.

Highlights

• Scheduled Agentflow Execution: Introduced first-class scheduled execution for Agentflows, allowing them to run on a recurring basis.
• UI Configuration for Schedules: Added new UI inputs on the Agentflow Start node for schedule configuration, supporting both cron expressions and a visual picker for frequency, time, and specific days.
• Backend Schedule Management: Implemented server-side persistence for schedules, including new database entities and migrations, along with validation and hooks for upserting or disabling schedules on chatflow save, update, and delete.
• Flexible Scheduling Mechanism: Developed a backend scheduler (ScheduleBeat) that can operate in two modes: delegating to BullMQ for repeatable jobs (queue mode) or using an in-process timer (non-queue mode) for execution.
• Worker Integration: Integrated the new scheduling functionality into the existing worker system, ensuring scheduled jobs are processed efficiently.

Changelog

• packages/components/nodes/agentflow/Start/Start.ts
  • Updated the node version to 1.2.
  • Introduced a 'Schedule Input' option for the agentflow start node.
  • Added comprehensive UI fields for schedule configuration, including cron expression, visual picker options (frequency, minute, time, day of week, day of month), timezone, and default input.
  • Implemented logic to process scheduled inputs, setting the question and scheduled timestamp for agentflow execution.
• packages/server/src/Interface.Schedule.ts
  • Added new interfaces for schedule queue application server and agentflow job data.
• packages/server/src/commands/worker.ts
  • Registered and initialized a new schedule worker.
  • Included the schedule worker in the graceful shutdown process.
• packages/server/src/database/entities/ScheduleRecord.ts
  • Introduced the ScheduleRecord entity to persist scheduling configurations, including cron expressions, timezones, and target IDs.
• packages/server/src/database/entities/ScheduleTriggerLog.ts
  • Added the ScheduleTriggerLog entity to track the status and details of each scheduled execution.
• packages/server/src/database/entities/index.ts
  • Included ScheduleRecord and ScheduleTriggerLog in the list of database entities.
• packages/server/src/database/migrations/mariadb/1772000000000-AddScheduleEntities.ts
  • Provided database migration scripts to create the schedule_record and schedule_trigger_log tables, including primary keys and indexes.
• packages/server/src/database/migrations/mariadb/index.ts
  • Updated migration index files to include the new schedule entities migration.
• packages/server/src/database/migrations/mysql/1772000000000-AddScheduleEntities.ts
  • Provided database migration scripts to create the schedule_record and schedule_trigger_log tables, including primary keys and indexes.
• packages/server/src/database/migrations/mysql/index.ts
  • Updated migration index files to include the new schedule entities migration.
• packages/server/src/database/migrations/postgres/1772000000000-AddScheduleEntities.ts
  • Provided database migration scripts to create the schedule_record and schedule_trigger_log tables, including primary keys and indexes.
• packages/server/src/database/migrations/postgres/index.ts
  • Updated migration index files to include the new schedule entities migration.
• packages/server/src/database/migrations/sqlite/1772000000000-AddScheduleEntities.ts
  • Provided database migration scripts to create the schedule_record and schedule_trigger_log tables, including primary keys and indexes.
• packages/server/src/database/migrations/sqlite/index.ts
  • Updated migration index files to include the new schedule entities migration.
• packages/server/src/index.ts
  • Ensured ScheduleBeat is initialized during application startup to manage scheduled tasks.
• packages/server/src/queue/QueueManager.ts
  • Introduced ScheduleQueue to handle scheduled jobs.
  • Integrated ScheduleQueue with Bull Board for administrative monitoring.
• packages/server/src/queue/ScheduleBeat.ts
  • Developed ScheduleBeat to manage the lifecycle of scheduled tasks.
  • Provided logic for cron expression parsing and matching.
  • Implemented execution of agentflows based on schedules, including logging and status updates.
• packages/server/src/queue/ScheduleQueue.ts
  • Implemented ScheduleQueue to enqueue and process scheduled agentflow executions.
  • Provided methods to add and remove repeatable jobs in BullMQ.
• packages/server/src/services/chatflows/index.ts
  • Integrated schedule management into chatflow save, update, and delete operations.
  • Ensured schedules are disabled or removed when an agentflow is deleted or its scheduling configuration becomes invalid.
  • Notified ScheduleBeat of schedule changes to keep the scheduler synchronized.
• packages/server/src/services/schedule/index.ts
  • Introduced a dedicated service for schedule management, encompassing CRUD operations for ScheduleRecord and ScheduleTriggerLog.
  • Provided robust cron expression validation and utilities for converting visual picker inputs into cron strings.
  • Implemented functions to enable/disable schedules and log their execution status.
• packages/server/src/services/validation/index.ts
  • Integrated schedule configuration validation into the flow validation process for startAgentflow nodes.
• packages/ui/src/ui-component/picker/MonthDaysPicker.jsx
  • Introduced MonthDaysPicker React component for UI-based monthly schedule configuration.
• packages/ui/src/ui-component/picker/TimePicker.jsx
  • Introduced TimePicker React component for UI-based time selection in schedules.
• packages/ui/src/ui-component/picker/WeekDaysPicker.jsx
  • Introduced WeekDaysPicker React component for UI-based weekly schedule configuration.
• packages/ui/src/utils/genericHelper.js
  • Updated genericHelper to include new custom input types for time, weekday, and month day pickers.
• packages/ui/src/views/agentflowsv2/AgentFlowNode.jsx
  • Modified AgentFlowNode to display specific icons on the 'Start' node, indicating whether the agentflow is triggered by chat, form, or a schedule.
• packages/ui/src/views/canvas/NodeInputHandler.jsx
  • Incorporated the new TimePicker, WeekDaysPicker, and MonthDaysPicker components into the NodeInputHandler for rendering schedule-related inputs.

Activity

• The pull request was created by prd-hoang-doan, introducing new scheduling functionality for AgentflowV2.
• The author provided a detailed overview of the changes, including UI inputs, backend persistence, and execution mechanisms.
• Database schema changes for schedule_record and schedule_trigger_log were outlined, along with migration instructions.
• A YouTube demo link was provided to showcase the new features.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive scheduling feature for Agentflows, including UI for configuration, database persistence, and a backend scheduler supporting both queue and non-queue modes. The implementation is well-structured, with clear separation of concerns. I have two main points of feedback: one regarding the robustness of the cron expression validation, which could be improved by breaking down complex regex into simpler, individual validations for better readability and error prevention, and another to improve code clarity by simplifying a method signature and its call sites.

[harshit-flowise]

Thanks @prd-hoang-doan for this PR. We are working on a similar request and I will be testing it this week. Will reach out to you soon.

[jchui-wd]

@prd-hoang-doan Thanks for implementing this, this is great. Just a few things we want addressed before we merge. I split them up into bugs that need fixing and nice-to-have follow-ups.

Bugs

1. scheduledAt always falls back to current time (Start.ts:357)

options.agentflowRuntime?.scheduledAt is never populated, so the fallback new Date().toISOString() always fires. I think we can just remove it unless we actually pass scheduledAt through agentflowRuntime.

2. ScheduleRecord not cleaned up when ChatFlow is deleted

deleteChatFlow only calls disableSchedulesForTarget() (sets enabled = false). The ScheduleRecord rows should be hard-deleted when their parent ChatFlow is removed. ScheduleTriggerLog rows are fine to keep.

3. Empty input gets injected into ChatMessage

If no defaultInput is set, an empty string (or <p></p> from the rich text editor) gets written into ChatMessage. Please add a guard in buildAgentflow.ts to skip empty/whitespace inputs and strip rich text wrapper tags before they hit ChatMessage.

4. Clear chat doesn't work for scheduled flows

When pressing clear chat in the chat window for scheduled flows, it only deletes the latest output since it deletes one chatId at a time. We should delete all chat messages related to the chatFlowId, not just the chatId.

5. There are a few merge conflicts that needs to be resolved.

---

Nice to Haves

1. If possible, we'd like to replace the setInterval + custom cron parser with node-cron for MODE=MAIN since it's a more robust tool.
2. nextRunAt is never populated in ScheduleRecord, it would be great to populate it after each run, add missed-run detection on startup, and wire up SKIPPED in ScheduleTriggerLog when the current date has passed nextRunAt. Note: SKIPPED is currently unused.
3. An enable/disable toggle so users can pause a schedule without switching input types and losing their config.
4. End date support for schedules, could be a date picker.
5. Unit tests would be great to have, we'll be fixing our current broken tests soon and can sort out the testing rubric together.

Let us know which ones you can pick up and we can handle any remaining ones. Thanks again!

[prd-hoang-doan]

@jchui-wd Thanks for the quick and detailed feedback — I’m glad to receive it.
For the bugs (1–5), I’ll address all of them and aim to complete the fixes by the end of this week.
For the nice-to-have items:

1. Replacing the current cron implementation with node-cron in MAIN mode sounds like a good improvement — I’ll include that update as well.
2. Good catch on nextRunAt and SKIPPED handling — I missed that part, and I’ll follow your suggestion.
3. For the enable/disable toggle, do you have a preferred location in mind? I was thinking it may be better placed outside the Start dialog for better visibility (for example near the top of the canvas or toolbar).

4. I’ll also add an end date field so scheduled jobs can stop automatically when needed.
5. Regarding unit tests, since the current test structure is still being stabilized, would it be okay if I add them in a follow-up once the testing rubric is clearer?

Please let me know if you’d prefer me to prioritize any item differently. Thanks again!

[harshit-flowise]

@prd-hoang-doan Let's just add the disable toggle in the red box area. Thanks a lot.

[jchui-wd]

Thanks for this, any order is alright. We will update our CONTRIBUTING.MD with proper testing standard soon, will follow up shortly.

[jchui-wd]

Hey @prd-hoang-doan, we updated our Contributing.md with a testing section:
https://github.com/FlowiseAI/Flowise/blob/main/CONTRIBUTING.md#testing

Let us know if you have any questions / concerns.

[prd-hoang-doan]

@jchui-wd Sure, I’ll create the unit tests following your instruction. Thanks for the update.

[prd-hoang-doan]

@jchui-wd @harshit-flowise , I updated the pull requests based on @jchui-wd suggestion. The PR includes bug fixes (except point #4). It seems that our current logic only deletes the last sessions (I tried opening multiple profiles with the same account). Users can delete all by viewing all messages, then clicking Delete All.

Besides, I also implemented nice-to-have things:

1. Use "node-cron" for the main mode.
2. Use "SKIPED" status for any outdated schedule during the worker processing the job
3. Add the switch toggle on the header.

4. Add unit tests for the scheduled services.

Please take your time reviewing my pull requests, and feel free to share your feedback.

[jchui-wd]

Thanks @prd-hoang-doan for doing the changes. I think they look good

Below evidences and video of my tests in local.

Regular CRON / Visual Picker

Cron Toggle On

Cron_Toggle_On.mp4

Cron Toggle Off

Cron_Toggle_Off.mp4

Invalid Cron

Invalid_Cron_Input.mp4

Weekly

Visual_Picker_Weekly.mp4

Monthly

Visual_Picker_Monthly.mp4

Hourly

Visual_Picker_Hourly.mp4

Daily

Visual_Picker_Daily.mp4

Server Restart Resumes Job / MODE=QUEUE

Server Restart Resumes Job

Server_Restart_Resumes_Job.mp4

BullMQ / MODE=QUEUE

Mode.Queue_Test.mp4

Toggles Off After End Date / Cannot Enable Past EndDate

Toggles Off After End Date

Toggle_Off_After_EndDate.mp4

Cannot Enable Past End Date

Cannot_Enable_Past_EndDate.mp4

Delete Flow or Change Inputs Removes ScheduleRecord

Delete Flow Deletes ScheduleRecord

Delete_Flow_Deletes_ScheduleRecord.mp4

Change Input Deletes ScheduleRecord

Change_Input_Deletes_ScheduleRecord.mp4

All Tests Passing

As for #4, we can deal and follow up with this internally.

Since this is a big feature and may overlap with some other of our ongoing work, we will have additional eyes later on. We are still coordinating a few things on our end so it might take a bit longer before we can merge it in. We will keep you posted.

EDIT:
Actually seems like there is an error:
CI is failing because some date columns in ScheduleRecord and ScheduleTriggerLog use type: 'timestamp', which isn't supported by SQLite.
If you remove database configs in .env just let it run on default using sqlite you can see the error when starting the server. Can you take a look?

build failing

[prd-hoang-doan]

@jchui-wd Thank you for your effort to review my code, test the feature, and point out the issue. I will fix check the build on sqlite to make sure the migration is correct.

[prd-hoang-doan]

@jchui-wd I push the latest commit to fix the issue with SQLite. I also tested with other database including mariadb, mysql as well. Please help me verify on your machine with SQLite database.

• SQLite

• MariaDB

• Unit tests:

[jchui-wd]

Thanks for applying the fix @prd-hoang-doan.

Confirmed running correctly on sql-lite, no errors

I also noticed two small issues and just pushed a fix:
(35a5802): added nullable: true to lastRunAt/nextRunAt/endDate on ScheduleRecord (entity didn't match migration DDL), and added IScheduleRecord/IScheduleTriggerLog interfaces per codebase convention.

Minor changes needed

[jchui-wd]

Confirmed with Jocelyn that editing Start.ts affects both the legacy canvas and the agentflow UI. We'd probably delay this merge to avoid unintended impacts on downstream or merge it in a separate feature branch.

[HenryHengZJ]

Thank you @prd-hoang-doan for the changes! Apologies if this is taking longer since we have to let some other PRs to get in first, but this should give us enough time to test this thoroughly

[prd-hoang-doan]

@HenryHengZJ Thanks for the update — no worries at all! I understand the process, and I appreciate you taking the time to test everything carefully.
Happy to wait, and feel free to let me know if anything needs to be adjusted on my side.

[jchui-wd]

@prd-hoang-doan hi again,

If you have time we would like some changes to help prevent cloud apps from being overloaded.

1. Enforce minimum 1-minute cron interval
node-cron v4 supports a 6th field (seconds), so * * * * * * would fire every second. We need to restrict to 5-field cron only.

• packages/server/src/services/schedule/utils.ts ~line 22 - validation currently accepts fields.length === 6, this should be rejected
• Same file ~line 84 — 6-field seconds handling can be removed
• packages/server/src/services/schedule/utils.test.ts ~line 32 - remove/update the 'accepts 6-field cron with seconds' test

2. Schedule executions need to count against prediction quota

• Right now ScheduleExecutor calls executeAgentFlow (packages/server/src/utils/buildAgentflow.ts) which doesn't go through checkPredictions/updatePredictionsUsage (those only live in packages/server/src/utils/buildChatflow.ts). Also orgId, subscriptionId, and productId are passed as empty strings in packages/server/src/queue/ScheduleExecutor.ts (lines 181-183).
• Each schedule fire is essentially a prediction, so it should be counted against the existing quota:predictions limit on cloud.

will be further tested

[prd-hoang-doan]

Hi @jchui-wd, I updated two mentioned points in the latest commit. Thank you for pointing out the usage issue.
Please take a look and review it.

[jchui-wd]

@prd-hoang-doan thanks for the quick turnaround.

Apologies, I have to go back on my Item Number 1 request.

Instead of rejecting 6-field cron entirely, can you revert that change and replace it with a minimum interval check in? Here's the updated approach:

• Add a MIN_SCHEDULE_INTERVAL_SECONDS env variable to the server (default 60)
• Add a new route e.g. GET /api/v1/schedule-config that returns { minScheduleIntervalSeconds: 60 } so the UI can fetch it
• When saving, if the cron interval is below MIN_SCHEDULE_INTERVAL_SECONDS. We can fire a error toast to tell them. "The CRON interval is less than the minimum interval X seconds".
• The server should block all enabling of runs that with CRON below the MIN_SCHEDULE_INTERVAL_SECONDS when saving.
• On the UI, disable the schedule toggle if the cron interval is less than MIN_SCHEDULE_INTERVAL_SECONDS with a warning message again "The cron interval is less than the minimum allowed interval of X seconds", similar to how the toggle is already disabled when the end date is in the past

---

Item Number 2 For this

I just want to make sure incase theres a bug for OSS users. Flowise OSS works without account registration, meaning the workspace and organization tables can be empty. If a user never registered an account, findOneBy returns null and the schedule crashes with "Workspace not found".

Can you wrap the workspace/org lookup and quota check in a platform guard so OSS skips it entirely?

if (identityManager.isCloud() || identityManager.isEnterprise()) {
    // existing workspace/org lookup and checkPredictions/updatePredictionsUsage
}

Thanks again for your patience!

[prd-hoang-doan]

Hi @jchui-wd, thank for your feedback, but I have some concerns below:
For #1, I think that we can use MIN_SCHEDULE_INTERVAL_MINUTES instead of SECONDS to avoid spamming jobs on the server. I tried using MIN_SCHEDULE_INTERVAL_SECONDS on my local, but it seems not to bring much value to validate */30 * * * * * (every 30 seconds) or */90 * * * * * (every 90 seconds). So, I suggest use MINUTES to control the interval between job schedulers. How do you think about this?

For #2, I followed the same pattern for the function utilBuildChatflow function. For the OOS Users like me, I can do anything without enterprise features and run unlimited predictions. The OOS users still have to set up the first account with the default organization and default workspace since most APIs use the column for query to avoid cross-access security issues.
https://github.com/FlowiseAI/Flowise/blob/main/packages/server/src/utils/buildChatflow.ts#L1053-L1055
Could you double-check that?

[jchui-wd]

@prd-hoang-doan

Ah I should have given more context.

For Number 1, we wanted to have MIN_SCHEDULE_INTERVAL_SECONDS over minutes is because we want to give users the flexibility to run sub-minute crons if they need to, for our own cloud we'd set it to 60, but self-hosted users could set it to 1 or whatever works for them.

Although I realize this might affect computeNextRunAt since it uses _cronMatchesParsed to calculate nextRunAt in the db. And changing the maxIterations to be seconds instead of minutes may cause slight performance issues.
(60 * 24 * 366 -> 60 * 60 * 24 * 366)

But I do think it is fine since from 1s - 60s the worse iteration per computeNextRunAt would be 60 iterations, which is not too bad. And the absolute worse 0 0 31 2 * only on Feb 31st which contains 31 million iterations which can never happen cause its Feb 31st.

So I think it is fine to have MIN_SCHEDULE_INTERVAL_SECONDS and change the calculations for maxIterations to be seconds.

Let me know your thoughts.

For Number 2, I did a double take and you're right and it is not an issue, thanks!

[prd-hoang-doan]

Hi @jchui-wd , I added MIN_SCHEDULE_INTERVAL_SECONDS env to allow the OSS user to control the interval between jobs. Users can set the interval as every second, or every 15 or 30 seconds.
If you have any feedback, feel free to let me know.