feat: add scheduler

[yaohuitc]

AgentScope-Java Version

1.0.1-SNAPSHOT

Description

Background

AgentScope-Java lacks built-in scheduling capabilities for agents to run at specified times or intervals. This limits automation and periodic task execution scenarios.

Purpose

Add a new agentscope-extensions-scheduler module that provides flexible scheduling capabilities for agents with distributed execution support.

Changes Made

Core Components:

• AgentConfig: Configuration class with factory-based agent creation for state isolation
• ScheduleConfig: Flexible scheduling configuration (Cron, fixed-rate, fixed-delay)
• AgentScheduler: Interface for managing scheduled agents
• ScheduleAgentTask: Interface for scheduled task lifecycle management
• XxlJobAgentScheduler: Implementation using XXL-Job distributed scheduler

Key Features:

• 🏭 Factory-based design: Dynamically create fresh Agent instances for each execution
• 🔒 State isolation: Each execution gets clean Agent state
• 📦 Resource efficiency: Share expensive resources (Model, Toolkit) while creating fresh state
• 🔄 Dynamic configuration: Load latest configuration at execution time
• 📊 Distributed scheduling: Built-in XXL-Job integration

Testing:

• 10 test files with 104 test methods
• 100% class coverage
• All public APIs tested with validation and state transition tests

How to Test

1. Build the project:
   mvn clean install
2. Run tests:
   cd agentscope-extensions/agentscope-extensions-scheduler
   mvn test

Checklist

Please check the following items before code is ready to be reviewed.

• Code has been formatted with mvn spotless:apply
• All tests are passing (mvn test)
• Javadoc comments are complete and follow project conventions
• Related documentation has been updated (e.g. links, examples, etc.)
• Code is ready for review

[cla-assistant]

All committers have signed the CLA.

[cla-assistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[codecov]

Codecov Report

❌ Patch coverage is 69.86301% with 88 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ensions/scheduler/xxljob/XxlJobAgentScheduler.java	46.83%	38 Missing and 4 partials ⚠️
...pe/extensions/scheduler/BaseScheduleAgentTask.java	47.61%	21 Missing and 1 partial ⚠️
...ensions/scheduler/config/DashScopeModelConfig.java	81.66%	2 Missing and 9 partials ⚠️
...xtensions/scheduler/config/RuntimeAgentConfig.java	75.75%	7 Missing and 1 partial ⚠️
...scope/extensions/scheduler/config/AgentConfig.java	87.09%	0 Missing and 4 partials ⚠️
...pe/extensions/scheduler/config/ScheduleConfig.java	97.61%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!