Dynamic Workers and Workflows documentation

Author: mia303

src/assets/images/workflows/dynamic-workflows.png

@@ -0,0 +1,8 @@
+---
+title: Dynamic Workers and Workflows
+description: Route Workflow runs into dynamically loaded Worker code while keeping durable Workflow steps and state.
+pcx_content_type: example
+external_link: /workflows/examples/dynamic-workers-and-workflows/
+sidebar:
+  order: 5
+---

src/content/docs/dynamic-workers/examples/dynamic-workers-and-workflows.mdx

@@ -0,0 +1,185 @@
+---
+title: Dynamic Workflows
+description: Create and run Workflow logic dynamically while keeping Workflow steps durable.
+pcx_content_type: example
+sidebar:
+  order: 3
+---
+
+import { TypeScriptExample, WranglerConfig } from "~/components";
+
+Use this pattern when your Worker needs to create and run many different Workflows dynamically, especially one-off Workflows that are generated for a single task.
+
+For example, an AI agent might decide at runtime to create a Workflow with these steps:
+
+1. Summarize a support ticket
+2. Wait for human approval
+3. Send a follow-up message
+
+With Dynamic Workers and Workflows, the Worker Loader, which loads Dynamic Workers, can create that Workflow on the spot, run it durably, and let Workflows handle retries, sleeping, and waiting for events. You do not need to pre-register a separate Workflow class for every run.
+
+## When to use this pattern
+
+Use this pattern when your workflow logic is not known at deploy time.
+
+This is useful when:
+
+- An agent generates workflow code for a specific task
+- End customers create workflows in a multi-tenant application
+- You need many short-lived or one-off Workflows without deploying a new Worker for each one
+
+If your workflow logic is fixed, a standard Workflow is generally recommended.
+
+## Understand the model
+
+This setup has two parts:
+
+- **Worker Loader**: Worker which receives the request and creates (or loads) the Dynamic Worker.
+- **Workflow class**: Your registered Workflow class which receives the persisted params, reloads the same Dynamic Worker code, and calls its `run()` method with the `WorkflowStep` object.
+
+![Dynamic Workers and Workflows architecture diagram](~/assets/images/workflows/dynamic-workflows.png)
+
+Once the Worker Loader has [loaded the Dynamic Worker](/dynamic-workers/getting-started/#run-a-dynamic-worker), the Dynamic Worker calls `env.WORKFLOW.create()` to trigger an instance of the Workflow. The Worker Loader then stores the `workerId` of the Dynamic Worker in case the isolate spins down during the Workflow's exeuction.
+
+If the instance is long-running -- for example, if it includes a step.waitForEvent() -- then the Workflow engine may hibernate, and the Dynamic Worker isolate will shut down until the event occurs. When the Workflow resumes, the Worker Loader reloads its code using the workerId of the `Dynamic Worker`.
+
+Following its normal durable execution model, the workflow instance continues where it left off, and the Dynamic Worker executes the remaining steps. The instance reaches completion with all steps durably executed, and the Dynamic Worker stops running.
+
+## Configure your Worker
+
+Your Worker needs two things:
+
+- A Worker Loader binding
+- A Workflow binding that points to the Workflow class
+
+<WranglerConfig>
+
+```jsonc
+{
+	"name": "dynamic-workflow-loader",
+	"main": "src/index.ts",
+	"compatibility_date": "$today",
+	"worker_loaders": [
+		{
+			"binding": "LOADER",
+		},
+	],
+	"workflows": [
+		{
+			"name": "dynamic-workflow",
+			"binding": "WORKFLOW",
+			"class_name": "DynamicWorkflow",
+		},
+	],
+}
+```
+
+</WranglerConfig>
+
+## Run the Dynamic Worker from your Workflow class
+
+Although the Workflow is not statically defined, you still deploy one normal Workflow class. Its job is to load the dynamic code for the current run and call it with the `WorkflowStep` object. This class is what makes the [Workflows API](/workflows/build/workers-api/), including `step.do()`, `step.sleep()`, and `step.waitForEvent()`, continue to work as normal.
+
+Use `env.LOADER.get(id, callback)` via the [Worker Loader API](/dynamic-workers/api-reference/#load) to create the Dynamic Worker. If the Dynamic Worker has already been created, the Worker Loader uses its `workerId` to reload the code and use the same Dynamic Worker.
+
+<TypeScriptExample>
+
+```ts
+import {
+	WorkflowEntrypoint,
+	type WorkflowStep,
+	type WorkflowEvent,
+} from "cloudflare:workers";
+
+type Params = {
+	script: string;
+};
+
+export class DynamicWorkflow extends WorkflowEntrypoint<Env, Params> {
+	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
+		const { script } = event.payload;
+
+		const worker = this.env.LOADER.get(
+			`dyn-wf-${event.instanceId}`,
+			async () => ({
+				mainModule: "index.js",
+				modules: { "index.js": script },
+				compatibilityDate: "2025-09-27",
+				compatibilityFlags: ["nodejs_compat"],
+			}),
+		);
+
+		const entrypoint = worker.getEntrypoint() as unknown as {
+			run(event: Record<string, unknown>, step: WorkflowStep): Promise<unknown>;
+		};
+		const result = await entrypoint.run({}, step);
+
+		return result;
+	}
+}
+```
+
+<TypeScriptExample>
+
+```ts
+function loadDynamicWorkflow(env: Env, scriptId: string, script: string) {
+	return env.LOADER.get(`dynamic-workflow:${scriptId}`, async () => ({
+		compatibilityDate: "$today",
+		mainModule: "index.js",
+		modules: {
+			"index.js": script,
+		},
+		globalOutbound: null,
+	}));
+}
+```
+
+</TypeScriptExample>
+
+## Write the dynamic workflow code
+
+The dynamic code defines the steps for one run. It is regular Worker code loaded at runtime.
+
+This example implements the support-ticket flow described earlier:
+
+1. Summarize the ticket
+2. Wait for approval
+3. Send a follow-up
+
+<TypeScriptExample>
+
+```ts
+import { WorkerEntrypoint } from "cloudflare:workers";
+
+export class DynamicWorkflowLogic extends WorkerEntrypoint {
+	async run(event, step) {
+		const summary = await step.do("summarize ticket", async () => {
+			const ticket = event.payload.ticket;
+			return `Summary: ${ticket.subject}`;
+		});
+
+		await step.waitForEvent("wait for approval", {
+			type: "ticket-approved",
+			timeout: "24 hours",
+		});
+
+		return step.do("send follow-up", async () => {
+			return {
+				sent: true,
+				message: `Approved follow-up sent for: ${summary}`,
+			};
+		});
+	}
+}
+```
+
+</TypeScriptExample>
+
+## Related resources
+
+- [Workers API](/workflows/build/workers-api/)
+- [Trigger Workflows](/workflows/build/trigger-workflows/)
+- [Events and parameters](/workflows/build/events-and-parameters/)
+- [Dynamic Workers getting started](/dynamic-workers/getting-started/)
+- [Dynamic Worker Loaders](/workers/runtime-apis/bindings/worker-loader/)
+- [Bindings with Dynamic Workers](/dynamic-workers/usage/bindings/)