scheduling

Scheduling

Schedule tasks to run in the future — whether that's seconds from now, at a specific date/time, or on a recurring cron schedule. Scheduled tasks survive agent restarts and are persisted to SQLite.

Overview

The scheduling system supports four modes:

Mode	Syntax	Use Case
Delayed	this.schedule(60, ...)	Run in 60 seconds
Scheduled	this.schedule(new Date(...), ...)	Run at specific time
Cron	this.schedule("0 8 * * *", ...)	Run on recurring schedule
Interval	this.scheduleEvery(30, ...)	Run every 30 seconds

Under the hood, scheduling uses Durable Object alarms to wake the agent at the right time. Tasks are stored in a SQLite table and executed in order.

Scheduler Lifecycle primitive

Experimental. The Scheduler primitive and the agents/lifecycle surface it builds on may change between releases. Agent's established scheduling methods (this.schedule() and friends) are stable.

Scheduler is a reusable Lifecycle capability. A plain Lifecycle Object can install it without extending Agent:

import { DurableObject } from "cloudflare:workers";
import { Lifecycle } from "agents/lifecycle";
import { Scheduler, type Schedule } from "agents/schedules";

export class ReminderObject extends DurableObject<Env> {
  readonly scheduler = new Scheduler({
    callbacks: {
      sendReminder: (
        payload: { message: string },
        schedule: Schedule<{ message: string }>
      ) => {
        console.log(schedule.id, payload.message);
      }
    }
  });

  readonly lifecycle = Lifecycle.install(this).use(this.scheduler);

  async createReminder(message: string): Promise<string> {
    const schedule = await this.scheduler.set(300, "sendReminder", {
      message
    });
    return schedule.id;
  }
}