From 44387e30a21e8ac2bbb93a3ce5cab71dae22ab13 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Fri, 30 Jan 2026 11:18:32 +0000
Subject: [PATCH] docs: add scheduleSchema documentation for natural language
 scheduling

Adds documentation for the scheduleSchema API which allows parsing natural
language scheduling requests using the AI SDK. This includes:

- Overview of scheduleSchema and getSchedulePrompt helpers
- Installation instructions for required AI SDK packages
- Complete usage example with OpenAI provider
- Important callout about required providerOptions for OpenAI compatibility

Synced from cloudflare/agents PR #815

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 .../agents/api-reference/schedule-tasks.mdx   | 47 ++++++++++++++++++-
 1 file changed, 46 insertions(+), 1 deletion(-)

diff --git a/src/content/docs/agents/api-reference/schedule-tasks.mdx b/src/content/docs/agents/api-reference/schedule-tasks.mdx
index bfb6079a95a..629b7d368f6 100644
--- a/src/content/docs/agents/api-reference/schedule-tasks.mdx
+++ b/src/content/docs/agents/api-reference/schedule-tasks.mdx
@@ -5,7 +5,7 @@ sidebar:
   order: 4
 ---
 
-import { MetaInfo, Render, Type, TypeScriptExample, WranglerConfig } from "~/components";
+import { MetaInfo, Render, Type, TypeScriptExample, WranglerConfig, PackageManagers } from "~/components";
 
 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.
 
@@ -17,6 +17,51 @@ You can safely call `this.destroy()` within a scheduled task callback. The Agent
 
 :::
 
+## Parsing natural language scheduling requests
+
+The `scheduleSchema` provides a structured way to parse natural language scheduling requests into a format that can be used with `this.schedule()`. This is useful when building agents that accept user input like "remind me tomorrow at 3pm" or "schedule a meeting next Monday".
+
+The schema uses the [AI SDK](https://sdk.vercel.ai/docs/introduction) to extract scheduling information from natural language text.
+
+To use `scheduleSchema`, install the required packages:
+
+<PackageManagers pkg="ai @ai-sdk/openai" />
+
+### scheduleSchema
+
+<TypeScriptExample>
+
+```ts
+import { generateObject } from "ai";
+import { scheduleSchema, getSchedulePrompt } from "agents/schedule";
+
+const result = await generateObject({
+  model,
+  prompt: `${getSchedulePrompt({ date: new Date() })} Input: "${userInput}"`,
+  schema: scheduleSchema,
+  // Required for OpenAI to avoid strict JSON schema validation errors
+  providerOptions: {
+    openai: { strictJsonSchema: false }
+  }
+});
+
+// result.object contains the parsed schedule information:
+// - description: string - A description of the task
+// - when: object - The parsed scheduling information
+```
+
+</TypeScriptExample>
+
+:::caution[OpenAI provider options required]
+
+When using `scheduleSchema` with OpenAI models via the AI SDK, you must pass `providerOptions: { openai: { strictJsonSchema: false } }` to `generateObject`. This is required because the schema uses optional fields which are not compatible with OpenAI's strict structured outputs mode.
+
+The `@ai-sdk/openai` package now defaults `strictJsonSchema` to `true`, which requires all schema properties to be in the `required` array.
+
+:::
+
+The `getSchedulePrompt()` helper function provides the system prompt that instructs the AI model how to parse scheduling requests. Pass the current date so the model can correctly interpret relative time expressions like "tomorrow" or "next week".
+
 ### Scheduling tasks
 
 You can call `this.schedule` within any method on an Agent, and schedule tens-of-thousands of tasks per individual Agent: