Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Known Vulnerabilities GitHub Workflow Status Coverage Maven Central Javadoc

A lightweight timer/cron agents framework for Java applications.

Agents overview

Convert any Java class into an Agent by adding the @Agent annotation at the class, then mark one method with the @Run annotation so it will be called automatically. The framework looks up for agent classes by scanning user-specified packages at runtime and can run particular tasks periodically in the JVM.

An agent can be of type Timer or Cron:

Timer agents

A Timer agent can be executed periodically, in a fixed run frequency, which must be in seconds, minutes, or hours. For example:

package com.mycompany.agents;
@Agent(type = AgentType.TIMER, interval = "30 seconds", modulate = true)
public class MyTimerAgent {
    public void execute() {
       // This method will be called every 30 seconds...

Cron agents

A Cron agent can be executed at specific dates and times, comparable to the Cron Service available in Unix/Linux systems. Although they are more robust in terms of configuration flexibility, the interval between executions cannot be lower than 1 minute.

Cron systax has five fields separated by a space, and each field represent a unit of time.

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of the month (1 - 31)
│ │ │ ┌───────────── month (1 - 12 or JAN-DEC)
│ │ │ │ ┌───────────── day of the week (0 - 6 or SUN-SAT)
│ │ │ │ │                                   
│ │ │ │ │
│ │ │ │ │
* * * * *

For example, the following agent is configured to execute every weekday at 2:00 AM:

package com.mycompany.agents;
@Agent(type = AgentType.CRON, interval = "0 2 * * MON-FRI")
public class MyCronAgent {
    public void execute() {
        // This method will be called every weekday at 2:00 AM


  1. Scan one or more base packages to search for agents
AgentManager manager = AgentManager.defaultInstance();
  1. Start all agents

How to include it

If you are using Maven, add Agents as a dependency on your pom.xml file:


If you use other dependency managers (such as Gradle, Grape, Ivy, etc.) click here.