Schedule tasks

An Agent can schedule tasks to be run in the future by calling this.schedule(when, callback, data), where when can be a delay, a Date, or a cron string; callback the function name to call, and data is an object of data to pass to the function.

Scheduled tasks can do anything a request or message from a user can: make requests, query databases, send emails, read+write state: scheduled tasks can invoke any regular method on your Agent.

Scheduling tasks

You can call this.schedule within any method on an Agent, and schedule tens-of-thousands of tasks per individual Agent:

JavaScript

import { Agent } from "agents-sdk";

export class SchedulingAgent extends Agent {
  async onRequest(request) {
    // Handle an incoming request
    // Schedule a task 5 minutes from now
    // Calls the "checkFlights" method
    let { taskId } = await this.schedule(600, "checkFlights", {
      flight: "DL264",
      date: "2025-02-23",
    });
    return Response.json({ taskId });
  }

  async checkFlights(data) {
    // Invoked when our scheduled task runs
    // We can also call this.schedule here to schedule another task
  }
}

TypeScript

import { Agent } from "agents-sdk"

export class SchedulingAgent extends Agent {
  async onRequest(request) {
    // Handle an incoming request
    // Schedule a task 5 minutes from now
    // Calls the "checkFlights" method
    let { taskId } = await this.schedule(600, "checkFlights", { flight: "DL264", date: "2025-02-23" });
    return Response.json({ taskId });
  }

  async checkFlights(data) {
    // Invoked when our scheduled task runs
    // We can also call this.schedule here to schedule another task
  }
}

Warning

Tasks that set a callback for a method that does not exist will throw an exception: ensure that the method named in the callback argument of this.schedule exists on your Agent class.

You can schedule tasks in multiple ways:

JavaScript

// schedule a task to run in 10 seconds
let task = await this.schedule(10, "someTask", { message: "hello" });

// schedule a task to run at a specific date
let task = await this.schedule(new Date("2025-01-01"), "someTask", {});

// schedule a task to run every 10 seconds
let { id } = await this.schedule("*/10 * * * *", "someTask", {
  message: "hello",
});

// schedule a task to run every 10 seconds, but only on Mondays
let task = await this.schedule("0 0 * * 1", "someTask", { message: "hello" });

// cancel a scheduled task
this.cancelSchedule(task.id);

TypeScript

// schedule a task to run in 10 seconds
let task = await this.schedule(10, "someTask", { message: "hello" });

// schedule a task to run at a specific date
let task = await this.schedule(new Date("2025-01-01"), "someTask", {});

// schedule a task to run every 10 seconds
let { id } = await this.schedule("*/10 * * * *", "someTask", { message: "hello" });

// schedule a task to run every 10 seconds, but only on Mondays
let task = await this.schedule("0 0 * * 1", "someTask", { message: "hello" });

// cancel a scheduled task
this.cancelSchedule(task.id);

Calling await this.schedule returns a Schedule, which includes the task's randomly generated id. You can use this id to retrieve or cancel the task in the future. It also provides a type property that indicates the type of schedule, for example, one of "scheduled" | "delayed" | "cron".

Maximum scheduled tasks

Each task is mapped to a row in the Agent's underlying SQLite database, which means that each task can be up to 2 MB in size. The maximum number of tasks must be (task_size * tasks) + all_other_state < maximum_database_size (currently 1GB per Agent).

Managing scheduled tasks

You can get, cancel and filter across scheduled tasks within an Agent using the scheduling API:

JavaScript

// Get a specific schedule by ID
// Returns undefined if the task does not exist
let task = await this.getSchedule(task.id);

// Get all scheduled tasks
// Returns an array of Schedule objects
let tasks = this.getSchedules();

// Cancel a task by its ID
// Returns true if the task was cancelled, false if it did not exist
await this.cancelSchedule(task.id);

// Filter for specific tasks
// e.g. all tasks starting in the next hour
let tasks = this.getSchedules({
  timeRange: {
    start: new Date(Date.now()),
    end: new Date(Date.now() + 60 * 60 * 1000),
  },
});

TypeScript

// Get a specific schedule by ID
// Returns undefined if the task does not exist
let task = await this.getSchedule(task.id)

// Get all scheduled tasks
// Returns an array of Schedule objects
let tasks = this.getSchedules();

// Cancel a task by its ID
// Returns true if the task was cancelled, false if it did not exist
await this.cancelSchedule(task.id);

// Filter for specific tasks
// e.g. all tasks starting in the next hour
let tasks = this.getSchedules({
  timeRange: {
    start: new Date(Date.now()),
    end: new Date(Date.now() + 60 * 60 * 1000),
  }
});