Sync documentation from PR #812

Updates:
- Add scheduleEvery() interval scheduling documentation
- Document custom routing with basePath and server-sent identity
- Add identity change handling and security options
- Update examples to follow Cloudflare docs style guide

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: github-actions[bot]

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

@@ -178,7 +178,139 @@ export class MyAgent extends Agent<Env> {
 ```
 </TypeScriptExample>
 
-Replace `userId` with `teamName`, `channel`, `companyName` as fits your Agents goals - and/or configure authentication to ensure Agents are only created for known, authenticated users.
+Replace `userId` with `teamName`, `channel`, `companyName` as fits your Agents goals - and configure authentication to ensure Agents are only created for known, authenticated users.
+
+### Custom routing with basePath
+
+For advanced use cases, you can bypass the default `/agents/:agent/:name` URL pattern and define custom routing. This is useful when the instance name should be determined server-side (for example, from authentication or session data) or when you need clean URLs without the `/agents/` prefix.
+
+**Client-side with basePath:**
+
+<TypeScriptExample>
+
+```ts
+import { useAgent } from "agents/react";
+
+// Connect to /user instead of /agents/user-agent/...
+const agent = useAgent({
+  agent: "UserAgent", // Required but ignored when basePath is set
+  basePath: "user" // Connects to /user
+});
+```
+
+</TypeScriptExample>
+
+**Server-side routing:**
+
+When using `basePath`, your Worker must handle the custom path and forward requests to the appropriate agent instance:
+
+<TypeScriptExample>
+
+```ts
+import { Agent, getAgentByName, routeAgentRequest } from "agents";
+
+export default {
+  async fetch(request: Request, env: Env) {
+    const url = new URL(request.url);
+
+    // Custom routing - server determines instance from session
+    if (url.pathname === "/user") {
+      const session = await getSession(request);
+      const agent = await getAgentByName(env.UserAgent, session.userId);
+      return agent.fetch(request); // Forward request directly to agent
+    }
+
+    // Default routing for standard /agents/... paths
+    return (
+      routeAgentRequest(request, env) ||
+      new Response("Not found", { status: 404 })
+    );
+  }
+};
+```
+
+</TypeScriptExample>
+
+**Server-sent identity:**
+
+When using `basePath`, clients do not know which instance they connected to until the server sends the identity. Agents automatically send their identity on connection:
+
+<TypeScriptExample>
+
+```ts
+const agent = useAgent({
+  agent: "UserAgent",
+  basePath: "user",
+  onIdentity: (name, agentType) => {
+    console.log(`Connected to ${agentType} instance: ${name}`);
+    // for example, "Connected to user-agent instance: user-123"
+  }
+});
+
+// Reactive state - re-renders when identity is received
+return (
+  <div>
+    {agent.identified ? `Connected to: ${agent.name}` : "Connecting..."}
+  </div>
+);
+```
+
+</TypeScriptExample>
+
+**Handling identity changes:**
+
+If the identity changes on reconnect (for example, session expired and user logs in as someone else), handle it with `onIdentityChange`:
+
+<TypeScriptExample>
+
+```ts
+const agent = useAgent({
+  agent: "UserAgent",
+  basePath: "user",
+  onIdentityChange: (oldName, newName, oldAgent, newAgent) => {
+    console.log(`Session changed: ${oldName} → ${newName}`);
+    // Refresh state, show notification, and more
+  }
+});
+```
+
+</TypeScriptExample>
+
+**Disabling identity for security:**
+
+If your instance names contain sensitive data (session IDs or internal user IDs), disable identity sending:
+
+<TypeScriptExample>
+
+```ts
+export class SecureAgent extends Agent {
+  // Do not expose instance names to clients
+  static options = { sendIdentityOnConnect: false };
+}
+```
+
+</TypeScriptExample>
+
+When identity is disabled:
+- `agent.identified` stays `false`
+- `agent.ready` never resolves (use state updates instead)
+- `onIdentity` and `onIdentityChange` are never called
+
+**Sub-paths with the path option:**
+
+Append additional path segments to the URL:
+
+<TypeScriptExample>
+
+```ts
+// With basePath: /user/settings
+useAgent({ agent: "UserAgent", basePath: "user", path: "settings" });
+
+// Standard routing: /agents/my-agent/room/settings
+useAgent({ agent: "MyAgent", name: "room", path: "settings" });
+```
+
+</TypeScriptExample>
 
 ### Authenticating Agents
 

src/content/docs/agents/api-reference/schedule-tasks.mdx

@@ -7,7 +7,7 @@ sidebar:
 
 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. For fixed-interval recurring tasks, use `this.scheduleEvery(intervalSeconds, callback, data)`.
 
 Scheduled tasks can do anything a request or message from a user can: make requests, query databases, send emails, read+write state: scheduled tasks can invoke any regular method on your Agent.
 
@@ -63,19 +63,22 @@ let task = await this.schedule(10, "someTask", { message: "hello" });
 // schedule a task to run at a specific date
 let task = await this.schedule(new Date("2025-01-01"), "someTask", {});
 
-// schedule a task to run every 10 minutes
+// schedule a task to run every 10 minutes (cron)
 let { id } = await this.schedule("*/10 * * * *", "someTask", { message: "hello" });
 
 // schedule a task to run every 10 minutes, but only on Mondays
 let task = await this.schedule("*/10 * * * 1", "someTask", { message: "hello" });
 
+// schedule a task to run every 30 seconds (interval)
+let task = await this.scheduleEvery(30, "pollData", { source: "api" });
+
 // cancel a scheduled task
 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. It also provides a `type` property that indicates the type of schedule, for example, one of `"scheduled" | "delayed" | "cron"`.
+Calling `await this.schedule` or `await this.scheduleEvery` 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. It also provides a `type` property that indicates the type of schedule, for example, one of `"scheduled" | "delayed" | "cron" | "interval"`.
 
 :::note[Maximum scheduled tasks]
 
@@ -89,6 +92,58 @@ You can safely call `this.destroy()` from within a scheduled task callback. The
 
 :::
 
+### Interval scheduling with scheduleEvery()
+
+For tasks that need to run at fixed intervals, use `this.scheduleEvery()`. Unlike cron expressions (which have minute-level precision), intervals support sub-minute timing and arbitrary durations:
+
+<TypeScriptExample>
+
+```ts
+// Poll an API every 30 seconds
+await this.scheduleEvery(30, "pollApi", { endpoint: "/updates" });
+
+// Health check every 45 seconds
+await this.scheduleEvery(45, "healthCheck", {});
+
+// Sync data every 90 seconds (cannot be expressed in cron)
+await this.scheduleEvery(90, "syncData", { destination: "warehouse" });
+```
+
+</TypeScriptExample>
+
+**Key differences from cron:**
+
+| Feature             | Cron                           | Interval               |
+| ------------------- | ------------------------------ | ---------------------- |
+| Minimum granularity | 1 minute                       | 1 second               |
+| Arbitrary intervals | No (must fit cron pattern)     | Yes                    |
+| Fixed schedule      | Yes (for example, every day at 8am) | No (relative to start) |
+| Overlap prevention  | No                             | Yes (built-in)         |
+
+**Overlap prevention**: If a callback takes longer than the interval, the next execution is skipped to prevent resource exhaustion. A warning is logged when this occurs.
+
+**Error resilience**: If a callback throws an error, the interval continues running. Only that specific execution fails.
+
+<TypeScriptExample>
+
+```ts
+export class PollingAgent extends Agent {
+	async onRequest() {
+		// Start polling every 30 seconds
+		await this.scheduleEvery(30, "poll", {});
+		return new Response("Polling started");
+	}
+
+	async poll() {
+		// If this takes longer than 30 seconds, the next execution is skipped
+		const data = await fetch("https://api.example.com/data");
+		await this.processData(await data.json());
+	}
+}
+```
+
+</TypeScriptExample>
+
 ### Managing scheduled tasks
 
 You can get, cancel and filter across scheduled tasks within an Agent using the scheduling API:
@@ -109,13 +164,19 @@ let tasks = this.getSchedules();
 await this.cancelSchedule(task.id);
 
 // Filter for specific tasks
-// e.g. all tasks starting in the next hour
+// for example, all tasks starting in the next hour
 let tasks = this.getSchedules({
 	timeRange: {
 		start: new Date(Date.now()),
 		end: new Date(Date.now() + 60 * 60 * 1000),
 	}
 });
+
+// Get only interval schedules
+let intervalTasks = this.getSchedules({ type: "interval" });
+
+// Get only cron schedules
+let cronTasks = this.getSchedules({ type: "cron" });
 ```
 
 </TypeScriptExample>