调度任务 · Cloudflare Agents docs

当代码需要创建循环 Think 轮次或确定性调度处理程序时，使用 getScheduledTasks()。Think 在启动时协调声明，为下一次发生存储持久化一次性调度，并在每次运行后重新设置下一次发生。

import { Think, defineScheduledTasks } from "@cloudflare/think";

export class DigestAgent extends Think {
	getDefaultTimezone() {
		return "Europe/London";
	}

	getScheduledTasks() {
		return defineScheduledTasks({
			weeklyCommitReport: {
				schedule: "every week on monday at 09:00",
				prompt:
					"Compile all my GitHub commits for the last week and send a concise summary.",
			},
			workout: {
				schedule: "every day at 08:00 in Europe/London",
				prompt: "Start my workout.",
			},
			customerDigest: {
				schedule: "every day at 09:00",
				timezone: "America/New_York",
				metadata: { workflowName: "customer-digest" },
				retry: { maxAttempts: 3 },
				handler: async ({
					idempotencyKey,
					scheduledFor,
					scheduleKind,
					timezone,
				}) => {
					await this.env.DIGEST_WORKFLOW.create({
						id: idempotencyKey,
						params: { scheduledFor, scheduleKind, timezone },
					});
				},
			},
		});
	}
}

import { Think, defineScheduledTasks } from "@cloudflare/think";

export class DigestAgent extends Think<Env> {
	getDefaultTimezone() {
		return "Europe/London";
	}

	getScheduledTasks() {
		return defineScheduledTasks({
			weeklyCommitReport: {
				schedule: "every week on monday at 09:00",
				prompt:
					"Compile all my GitHub commits for the last week and send a concise summary.",
			},
			workout: {
				schedule: "every day at 08:00 in Europe/London",
				prompt: "Start my workout.",
			},
			customerDigest: {
				schedule: "every day at 09:00",
				timezone: "America/New_York",
				metadata: { workflowName: "customer-digest" },
				retry: { maxAttempts: 3 },
				handler: async ({
					idempotencyKey,
					scheduledFor,
					scheduleKind,
					timezone,
				}) => {
					await this.env.DIGEST_WORKFLOW.create({
						id: idempotencyKey,
						params: { scheduledFor, scheduleKind, timezone },
					});
				},
			},
		});
	}
}

DSL 支持 every <n> minutes、every <n> hours、every day at HH:mm、every weekday at HH:mm 和 every week on monday,wednesday at HH:mm。挂钟调度需要内联时区、任务 timezone 或 getDefaultTimezone()。若 alarm 延迟，Think 运行预期发生一次并调度下一次未来发生；不会回填错过的运行。

每个任务必须恰好定义 prompt 或 handler 之一。提示词任务通过 submitMessages() 创建持久化提交。处理程序任务接收 { taskId, scheduledFor, scheduledForDate, occurrenceKey, idempotencyKey, schedule, scheduleKind, timezone, metadata }，用于应用自有工作，例如创建 Workflow 运行或写入运行账本。交付为至少一次；对你自己的持久化幂等性使用 idempotencyKey 或 occurrenceKey。

静态声明在启动时协调。若 getScheduledTasks() 读取 Durable Object 存活期间可能变化的产品自有数据，更新该数据后调用 internal_reconcileScheduledTasks()。协调期间 Think 在创建底层 Agent 调度之前记录任务行，因此缺少 schedule_id 仅为待协调状态，会在下次协调时修复。任务 retry 选项在失败记录前重试提示词或处理程序操作。下一次发生仍在操作成功或重试耗尽后调度，因此失败的发生不会阻塞未来运行。

何时改用 Workflow

对于步骤重要的循环作业——多个确定性步骤、长时间等待或人工审批——使用处理程序任务创建 Think Workflow 运行。简单循环提示词保留为提示词任务，一次性后台轮次使用 submitMessages()。