limits, schedules

Author: elithrar

src/content/docs/agents/api-reference/configuration.mdx

@@ -1,28 +1,69 @@
 ---
-title: Agents SDK
+title:
 pcx_content_type: concept
 sidebar:
-  order: 2
+  order: 3
 
 ---
 
 import { MetaInfo, Render, Type, WranglerConfig } from "~/components";
 
-This guide details the Agents API within Cloudflare Workers, including methods, types, and usage examples.
+An Agent is configured like any other Cloudflare Workers project, and uses [a wrangler configuration](/workers/wrangler/configuration/) file to define where your code is and what services (bindings) it will use.
 
-## Agent
+The typical file structure for an Agent project created from `npm create cloudflare@latest -- --template cloudflare/agents` follows:
 
-TODO
+```sh
+.
+|-- package-lock.json
+|-- package.json
+|-- public
+|   `-- index.html
+|-- src
+|   `-- index.ts // your Agent definition
+|-- test
+|   |-- index.spec.ts // your tests
+|   `-- tsconfig.json
+|-- tsconfig.json
+|-- vitest.config.mts
+|-- worker-configuration.d.ts
+`-- wrangler.jsonc // your Workers & Agent configuration
+```
 
-The `Agent` class is the core element of a Agent definition:
+Below is a minimal `wrangler.jsonc` file that defines the configuration for an Agent, including the entry point,  `durable_object` namespace, and code `migrations`:
 
-```ts
-import { Agent } from "@cloudflare/agents";
+<WranglerConfig>
 
-export class MyAgent extends Agent<Env> {
-	// methods here
-	async onRequest(req: Request) {
-		
-	}
-};
-```
+```jsonc
+{
+	"$schema": "node_modules/wrangler/config-schema.json",
+	"name": "agents-example",
+	"main": "src/index.ts",
+	"compatibility_date": "2025-02-23",
+	"compatibility_flags": ["nodejs_compat"],
+	"durable_objects": {
+		"bindings": [
+			{
+				"name": "MyAgent",
+				"class_name": "MyAgent",
+			},
+		],
+	},
+	"migrations": [
+		{
+			"tag": "v1",
+			"new_sqlite_classes": ["MyAgent"], // Mandatory
+		},
+	],
+	"observability": {
+		"enabled": true,
+	},
+}
+```
+
+</WranglerConfig>
+
+The configuration includes:
+
+- A `main` field that points to the entry point of your Agent, which is typically a TypeScript (or JavaScript) file.
+- A `durable_objects` field that defines the [Durable Object namespace](/durable-objects/reference/glossary/) that your Agents will run within.
+- A `migrations` field that defines the code migrations that your Agent will use. This field is mandatory and must contain at least one migration.

src/content/docs/agents/api-reference/sdk.mdx

@@ -1,31 +1,11 @@
 ---
-title: Configuration
+title: Agents SDK
 pcx_content_type: concept
 sidebar:
-  order: 3
+  order: 2
 
 ---
 
 import { MetaInfo, Render, Type, WranglerConfig } from "~/components";
 
-TODO - how to configure an Agent
-
-<WranglerConfig>
-
-```json
-{
-  "name": "my-agent",
-  "script": "src/index.ts",
-  // @cloudflare/agents uses Durable Objects
-  "durable_objects": {
-    "bindings": [
-      {
-        "binding": "MyAgent",
-        "class_name": "MyAgent"
-      }
-    ]
-  }
-}
-```
-
-</WranglerConfig>
+Each Agent is a JavaScript class that extends the `Agent` class from the `@cloudflare/workers-agents` package. Agents are designed to run in a separate thread from the main Worker, allowing them to perform long-running tasks without blocking the main thread.

src/content/docs/agents/examples/schedule-tasks.mdx

@@ -3,28 +3,29 @@ title: Schedule tasks
 pcx_content_type: concept
 sidebar:
   order: 5
-
 ---
 
 import { MetaInfo, Render, Type, TypeScriptExample, WranglerConfig } 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.
+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, etc.
 
 ### Scheduling tasks
 
-You can call `this.schedule` within any method on an Agent:
+You can call `this.schedule` within any method on an Agent, and schedule tens-of-thousands of tasks per individual Agent.
 
 <TypeScriptExample>
 
 ```ts
 // schedule a task to run in 10 seconds
-this.schedule(10, "myTask", { message: "hello" });
+let task = await this.schedule(10, "myTask", { message: "hello" });
 
 // schedule a task to run at a specific date
-this.schedule(new Date("2025-01-01"), "myTask", { message: "hello" });
+let task = await this.schedule(new Date("2025-01-01"), "myTask", { message: "hello" });
 
 // schedule a task to run every 10 seconds
-this.schedule("*/10 * * * *", "myTask", { message: "hello" });
+let { id } = await this.schedule("*/10 * * * *", "myTask", { message: "hello" });
 
 // schedule a task to run every 10 seconds, but only on Mondays
 let task = await this.schedule("0 0 * * 1", "myTask", { message: "hello" });
@@ -35,6 +36,13 @@ this.cancelSchedule(task.id);
 
 </TypeScriptExample>
 
+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.
+
+:::note[Maximum scheduled tasks]
+
+Each task is mapped to a row in the Agent's underlying [SQLite database](/sqlite-in-durable-objects/), which means that each task can be up to 2MB 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
 
@@ -44,17 +52,20 @@ You can get, cancel and filter across scheduled tasks within an Agent using the
 
 ```ts
 // 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
-let tasks = await this.getScheduledTasks();
+// 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({ // returns an iterator
+let tasks = this.getSchedules({
 	timeRange: {
 		start: new Date(Date.now()),
 		end: new Date(Date.now() + 60 * 60 * 1000),

src/content/docs/agents/reference/limits.mdx

@@ -0,0 +1,31 @@
+---
+pcx_content_type: concept
+title: Limits
+sidebar:
+  order: 4
+
+---
+
+import { Render } from "~/components"
+
+Limits that apply to authoring, deploying, and running Agents are detailed below.
+
+Many limits are inherited from those applied to Workers scripts and/or Durable Objects, and are detailed in the [Workers limits](/workers/platform/limits/) documentation.
+
+::: note
+
+| Feature                                   | Limit         			    |
+| ----------------------------------------- | ----------------------- |
+| Max concurrent (running) Agents per account	| Tens of millions+ [^1]
+| Max definitions per account         | ~250,000+ [^2]
+| Max state stored per unique Agent | 1GB |
+| Max compute time per Agent | 30 seconds (refreshed per HTTP request / incoming WebSocket message) [^3] |
+| Duration (wall clock) per step [^3]       | Unlimited (e.g. waiting on a database call or an LLM response) |
+
+---
+
+[^1]: Yes, really. You can have tens of millions of Agents running concurrently, as each Agent is mapped to a [unique Durable Object](/durable-objects/what-are-durable-objects/) (actor).
+[^2]: You can deploy up to [500 scripts per account](/workers/platform/limits/), but each script (project) can define multiple Agents. Each deployed script can be up to 10MB on the [Workers Paid Plan](/workers/platform/pricing/#workers)
+[^3]: Compute (CPU) time per Agent is limited to 30 seconds, but this is refreshed when an Agent receives a new HTTP request, runs a [scheduled task](/agents/examples/schedule-tasks/), or an incoming WebSocket message.
+
+<Render file="limits_increase" product="workers" />