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.