スケジュールタスク

定期的な 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() のいずれかが必要です。アラームが遅れた場合、Think は本来の発生を 1 回実行し、次の未来の発生をスケジュールします。取りこぼした実行は後から埋めません。

各タスクは prompt か handler のどちらか一方だけを定義します。プロンプトタスクは submitMessages() で耐久的な受付を作ります。ハンドラータスクは { taskId, scheduledFor, scheduledForDate, occurrenceKey, idempotencyKey, schedule, scheduleKind, timezone, metadata } を受け取ります。Workflow 実行の作成や、実行台帳への書き込みなど、アプリ所有の作業向けです。配信は少なくとも 1 回（at-least-once）です。独自の耐久的なべき等には idempotencyKey または occurrenceKey を使います。

静的な宣言は起動時に突き合わせます。getScheduledTasks() が、Durable Object の稼働中に変わりうるプロダクト所有データを読む場合は、そのデータを更新したあとに internal_reconcileScheduledTasks() を呼びます。突き合わせ中、Think は基盤の Agent スケジュールを作る前にタスク行を記録します。そのため、欠けた schedule_id は保留中の突き合わせ状態にすぎず、次の突き合わせで修復されます。タスクの retry オプションは、失敗がログされる前にプロンプトまたはハンドラーを再試行します。次の発生は、アクションが成功するか再試行を使い切ったあともスケジュールされます。失敗した発生が、以降の実行を止めません。

ワークフローを使う場合

定期ジョブのステップが重要なとき（複数の決定的ステップ、長い待機、人間の承認）は、ハンドラータスクで Think Workflow 実行を作ります。単純な定期プロンプトはプロンプトタスクのままにし、一度きりのバックグラウンドターンは submitMessages() に置きます。