ScheduleHandle

A ScheduleHandle represents a recurring agent job. Created via agent.schedule() or resumed via client.schedule(id).

const schedule = await agent.schedule({
    cron: "0 9 * * 1-5",
    prompt: "Review recent commits for security issues",
});
// or
const schedule = client.schedule("schedule-id");

Properties

schedule.id

The schedule ID.

Type: string (readonly)

---

Methods

schedule.trigger()

Trigger the schedule immediately, bypassing the cron. Returns a TaskHandle for the resulting run.

const task = await schedule.trigger();
const result = await task.result({ timeoutMs: 120_000 });
console.log(result.text);

Returns: Promise<TaskHandle>

---

schedule.pause()

Disable the cron trigger. The schedule still exists but won't fire automatically.

await schedule.pause();

Returns: Promise<void>

---

schedule.resume()

Re-enable the cron trigger.

await schedule.resume();

Returns: Promise<void>

---

schedule.update(opts)

Update the schedule configuration.

await schedule.update({
    cron: "0 9 * * *", // change from weekdays to daily
    prompt: "Updated prompt",
    model: "anthropic/claude-sonnet-4-20250514",
});

• cron string — New cron expression.
• prompt string — New prompt for each run.
• model string — New model ID.
• enabled boolean — Enable or disable the schedule.
• config Config — New agent configuration.

Returns: Promise<void>

---

schedule.delete()

Delete the schedule permanently. Future cron triggers are cancelled.

await schedule.delete();

Returns: Promise<void>

---

Types

ScheduleInfo

Returned by client.listSchedules():

interface ScheduleInfo {
    id: string;
    cron: string;
    prompt: string;
    model: string;
    config: string | null;
    enabled: number; // 1 = active, 0 = paused
    timeCreated: number;
}

CreateScheduleOpts

Passed to agent.schedule():

interface CreateScheduleOpts {
    cron: string; // required — cron expression
    prompt: string; // required — what the agent should do each run
    model?: string; // optional — override the agent's model
}