workflow 5.0.0-beta.0 → 5.0.0-beta.2

package/docs/deploying/world/postgres-world.mdx

@@ -53,7 +53,8 @@ Create an `instrumentation.ts` file in your project root:
 export async function register() {
   if (process.env.NEXT_RUNTIME !== "edge") {
     const { getWorld } = await import("workflow/runtime");
-    await getWorld().start?.();
+    const world = await getWorld();
+    await world.start?.();
   }
 }
 ```
@@ -73,7 +74,8 @@ import type { ServerInit } from "@sveltejs/kit";
 
 export const init: ServerInit = async () => {
   const { getWorld } = await import("workflow/runtime");
-  await getWorld().start?.();
+  const world = await getWorld();
+  await world.start?.();
 };
 ```
 
@@ -92,7 +94,8 @@ import { defineNitroPlugin } from "nitro/~internal/runtime/plugin";
 
 export default defineNitroPlugin(async () => {
   const { getWorld } = await import("workflow/runtime");
-  await getWorld().start?.();
+  const world = await getWorld();
+  await world.start?.();
 });
 ```
 
@@ -138,7 +141,7 @@ If `WORKFLOW_POSTGRES_URL` is not set, the CLI defaults to `postgres://world:wor
 
 Learn more in the [Observability](/docs/observability) documentation.
 
-## Testing & Performance
+## Testing & Compatibility
 
 <WorldTestingPerformance />
 
@@ -168,7 +171,8 @@ For higher worker concurrency, Graphile Worker recommends setting `maxPoolSize`
 
 ### Programmatic configuration
 
-{/* @skip-typecheck: incomplete code sample */}
+{/*@skip-typecheck: incomplete code sample*/}
+
 ```typescript title="workflow.config.ts" lineNumbers
 import { createWorld } from "@workflow/world-postgres";
 
@@ -200,6 +204,7 @@ Deploy your application to any cloud that supports long-running servers:
 - Platform-as-a-Service providers (Railway, Render, Fly.io, etc.)
 
 Ensure your deployment has:
+
 1. Network access to your PostgreSQL database
 2. Environment variables configured correctly
 3. The `start()` function called on server initialization

package/docs/deploying/world/vercel-world.mdx

@@ -83,7 +83,7 @@ npx workflow inspect runs \
 
 Learn more in the [Observability](/docs/observability) documentation.
 
-## Testing & Performance
+## Testing & Compatibility
 
 <WorldTestingPerformance />
 

package/docs/errors/start-invalid-workflow-function.mdx

@@ -123,7 +123,7 @@ Before calling `start()`:
 1. Confirm the function includes `"use workflow"` as its first statement.
 2. Confirm your framework integration is enabled (for Next.js, wrap `next.config.ts` with [`withWorkflow()`](/docs/api-reference/workflow-next/with-workflow)).
 3. Pass the imported workflow function directly to `start()`, not a wrapper callback.
-4. Keep the function in a file that goes through Workflow DevKit's transform step.
+4. Keep the function in a file that goes through Workflow SDK's transform step.
 
 ## Related
 

package/docs/getting-started/index.mdx

@@ -8,7 +8,7 @@ related:
   - /docs/foundations/workflows-and-steps
 ---
 
-import { Next, Nitro, SvelteKit, Nuxt, Hono, Bun, AstroDark, AstroLight, TanStack, Vite, Express, Nest, Fastify } from "@/app/[lang]/(home)/components/frameworks";
+import { Next, Nitro, SvelteKit, Nuxt, Hono, Bun, AstroDark, AstroLight, TanStack, Vite, Express, Nest, Fastify, Python } from "@/app/[lang]/(home)/components/frameworks";
 
 <Cards>
     <Card href="/docs/getting-started/next">
@@ -63,6 +63,13 @@ import { Next, Nitro, SvelteKit, Nuxt, Hono, Bun, AstroDark, AstroLight, TanStac
         <span className="font-medium">SvelteKit</span>
      </div>
     </Card>
+    <Card href="/docs/getting-started/python">
+      <div className="flex flex-col items-center justify-center gap-2">
+        <Python className="size-16" />
+        <span className="font-medium">Python</span>
+        <Badge variant="secondary">Beta</Badge>
+      </div>
+    </Card>
     <Card className="opacity-50">
       <div className="flex flex-col items-center justify-center gap-2">
         <Nest className="size-16 dark:invert grayscale" />

package/docs/getting-started/meta.json

@@ -9,7 +9,8 @@
     "nitro",
     "nuxt",
     "sveltekit",
-    "vite"
+    "vite",
+    "python"
   ],
   "defaultOpen": true
 }

package/docs/getting-started/next.mdx

@@ -281,6 +281,30 @@ Upgrade to `workflow@4.0.1-beta.26` or later:
 workflow@latest
 ```
 
+### Turborepo caching
+
+If you're using [Turborepo](https://turbo.build/repo) in a monorepo, you need to include the generated Workflow routes in your cache outputs. The Workflow SDK generates route handlers at `app/.well-known/workflow/` (or `src/app/.well-known/workflow/` if your project uses the `src` directory) during the build process, and these files must be cached alongside your Next.js build output.
+
+Add the following to your `turbo.json`:
+
+```jsonc title="turbo.json"
+{
+  "tasks": {
+    "build": {
+      "outputs": [
+        ".next/**",
+        "!.next/cache/**",
+        // Include whichever path matches your project layout
+        "app/.well-known/workflow/**",
+        "src/app/.well-known/workflow/**"
+      ]
+    }
+  }
+}
+```
+
+Without this configuration, you may experience intermittent issues where workflows fail to register properly on cache hits, while working correctly on cache misses.
+
 ### `start()` says it received an invalid workflow function
 
 If you see this error:

package/docs/getting-started/python.mdx

@@ -0,0 +1,165 @@
+---
+title: Python
+description: Build durable workflows and AI agents in Python with the Vercel SDK.
+type: guide
+summary: Set up the Workflow Python SDK in your Python application.
+prerequisites:
+  - /docs/getting-started
+related:
+  - /docs/foundations
+  - /docs/foundations/workflows-and-steps
+---
+
+<Callout type="warn">
+The Python SDK is currently in **beta**. APIs and behavior may change. For the latest documentation and updates, see the [official Vercel Workflow Python documentation](https://vercel.com/docs/workflow/python?language=py).
+</Callout>
+
+You can build durable workflows in Python using the [`vercel` Python SDK](https://pypi.org/project/vercel/). Your workflow code can pause, resume, and maintain state, just like the JavaScript and TypeScript Workflow SDK.
+
+## Getting Started
+
+Install the `vercel` package:
+
+```bash filename="Terminal"
+pip install vercel
+```
+
+Configure `experimentalServices` in your `vercel.json`:
+
+```json filename="vercel.json"
+{
+  "experimentalServices": {
+    "ai_content_workflow": {
+      "type": "worker",
+      "entrypoint": "app/workflows/ai_content_workflow.py",
+      "topics": ["__wkf_*"]
+    }
+  }
+}
+```
+
+## Workflows
+
+A workflow is a stateful function that coordinates multi-step logic over time. Create a `Workflows` instance and use the `@wf.workflow` decorator to mark a function as durable:
+
+```python filename="app/workflow.py" {3}
+from vercel import workflow
+
+wf = workflow.Workflows()
+```
+
+```python filename="app/workflows/ai_content_workflow.py" {3}
+from app.workflow import wf
+
+@wf.workflow
+async def ai_content_workflow(*, topic: str):
+    draft = await generate_draft(topic=topic)
+    summary = await summarize_draft(draft=draft)
+
+    return {
+        "draft": draft,
+        "summary": summary,
+    }
+```
+
+Under the hood, the workflow compiles into a route that orchestrates execution. All inputs and outputs are recorded in an event log. If a deploy or crash happens, the system replays execution deterministically from where it stopped.
+
+## Steps
+
+A step is a stateless function that runs a unit of durable work inside a workflow. Use `@wf.step` to mark a function as a step:
+
+```python filename="app/steps/generate_draft.py" {4,8}
+import random
+from app.workflow import wf
+
+@wf.step
+async def generate_draft(*, topic: str):
+    return await ai_generate(prompt=f"Write a blog post about {topic}")
+
+@wf.step
+async def summarize_draft(*, draft: str):
+    summary = await ai_summarize(text=draft)
+
+    # Simulate a transient error. The step automatically retries.
+    if random.random() < 0.3:
+        raise Exception("Transient AI provider error")
+
+    return summary
+```
+
+Each step compiles into an isolated route. While the step executes, the workflow suspends without consuming resources. When the step completes, the workflow resumes automatically where it left off.
+
+## Sleep
+
+Sleep pauses a workflow for a specified duration without consuming compute resources:
+
+```python filename="app/workflows/ai_refine.py" {7}
+from vercel import workflow
+
+@wf.workflow
+async def ai_refine_workflow(*, draft_id: str):
+    draft = await fetch_draft(draft_id)
+
+    await workflow.sleep("7 days")  # Wait 7 days to gather more signals.
+
+    refined = await refine_draft(draft)
+
+    return {
+        "draft_id": draft_id,
+        "refined": refined,
+    }
+```
+
+The sleep call pauses the workflow and consumes no resources. The workflow resumes automatically when the time expires.
+
+## Hooks
+
+A hook lets a workflow wait for external events such as user actions, webhooks, or third-party API responses.
+
+Define a hook model with Pydantic and `workflow.BaseHook`:
+
+```python filename="app/workflows/approval.py" {3,14}
+from vercel import workflow
+
+class Approval(BaseModel, workflow.BaseHook):
+    """Human approval for AI-generated drafts"""
+
+    decision: Literal["approved", "changes"]
+    notes: str | None = None
+
+@wf.workflow
+async def ai_approval_workflow(*, topic: str):
+    draft = await generate_draft(topic=topic)
+
+    # Wait for human approval events
+    async for event in Approval.wait(token="draft-123"):
+        if event.decision == "approved":
+            await publish_draft(draft)
+            break
+
+        revised = await refine_draft(draft, event.notes)
+        await publish_draft(revised)
+```
+
+Resume the workflow when data arrives:
+
+```python filename="app/api/resume.py" {5}
+@app.post("/api/resume")
+async def resume(approval: Approval):
+    """Resume the workflow when an approval is received"""
+
+    await approval.resume("draft-123")
+    return {"ok": True}
+```
+
+When a hook receives data, the workflow resumes automatically. You don&apos;t need polling, message queues, or manual state management.
+
+## Learn More
+
+For comprehensive documentation, examples, and the latest updates, visit the [official Vercel Workflow Python documentation](https://vercel.com/docs/workflow/python).
+
+## Next Steps
+
+- Learn more about the [Foundations](/docs/foundations).
+- Check [Errors](/docs/errors) if you encounter issues.
+- Explore the [API Reference](/docs/api-reference).

package/docs/how-it-works/code-transform.mdx

@@ -89,20 +89,21 @@ export async function createUser(email: string) {
 
 {/* @skip-typecheck: incomplete code sample */}
 ```typescript
-import { registerStepFunction } from "workflow/internal/private"; // [!code highlight]
-
 export async function createUser(email: string) {
   return { id: crypto.randomUUID(), email };
 }
-
-registerStepFunction("step//workflows/user.js//createUser", createUser); // [!code highlight]
+(function(__wf_fn, __wf_id) { // [!code highlight]
+    var __wf_sym = Symbol.for("@workflow/core//registeredSteps"), __wf_reg = globalThis[__wf_sym] || (globalThis[__wf_sym] = new Map()); // [!code highlight]
+    __wf_reg.set(__wf_id, __wf_fn); // [!code highlight]
+    __wf_fn.stepId = __wf_id; // [!code highlight]
+})(createUser, "step//workflows/user.js//createUser"); // [!code highlight]
 ```
 
 **What happens:**
 
 - The `"use step"` directive is removed
 - The function body is kept completely intact (no transformation)
-- The function is registered with the runtime using `registerStepFunction()`
+- The function is registered with the runtime via an inline IIFE (no imports needed)
 - Step functions run with full Node.js/Deno/Bun access
 
 **Why no transformation?** Step functions execute in your main runtime with full access to Node.js APIs, file system, databases, etc. They don't need any special handling—they just run normally.

package/docs/meta.json

@@ -10,6 +10,7 @@
     "testing",
     "deploying",
     "errors",
+    "migration-guides",
     "api-reference"
   ]
 }

package/docs/migration-guides/index.mdx

@@ -0,0 +1,34 @@
+---
+title: Migration Guides
+description: Move your existing durable workflow system to the Workflow SDK with side-by-side code comparisons and a realistic migration example.
+type: overview
+summary: Migrate from Temporal, Inngest, AWS Step Functions, or trigger.dev to the Workflow SDK.
+related:
+  - /docs/foundations/workflows-and-steps
+  - /docs/getting-started
+---
+
+<Callout type="info">
+Install the Workflow SDK migration skill:
+
+```bash
+npx skills add https://github.com/vercel/workflow --skill migrating-to-workflow-sdk
+```
+</Callout>
+
+Move an existing orchestration system to the Workflow SDK. Each guide pairs a concept-mapping table with side-by-side code, so you can translate one piece of your codebase at a time.
+
+<Cards>
+    <Card href="/docs/migration-guides/migrating-from-temporal" title="Migrating from Temporal">
+        Map Activities, Workers, Signals, and Child Workflows onto workflows, steps, hooks, and `start()` / `getRun()`.
+    </Card>
+    <Card href="/docs/migration-guides/migrating-from-inngest" title="Migrating from Inngest">
+        Map `createFunction`, `step.run`, `step.sleep`, `step.waitForEvent`, and `step.invoke` onto workflows, steps, and hooks.
+    </Card>
+    <Card href="/docs/migration-guides/migrating-from-aws-step-functions" title="Migrating from AWS Step Functions">
+        Replace ASL JSON states, Task / Choice / Wait / Parallel states, and `.waitForTaskToken` callbacks with TypeScript.
+    </Card>
+    <Card href="/docs/migration-guides/migrating-from-trigger-dev" title="Migrating from trigger.dev">
+        Map `task()`, `schemaTask()`, `wait.for` / `wait.forToken`, `triggerAndWait`, and `metadata.stream` onto workflows, steps, hooks, and `start()` / `getRun()`.
+    </Card>
+</Cards>

package/docs/migration-guides/meta.json

@@ -0,0 +1,9 @@
+{
+  "title": "Migration Guides",
+  "pages": [
+    "migrating-from-temporal",
+    "migrating-from-inngest",
+    "migrating-from-aws-step-functions",
+    "migrating-from-trigger-dev"
+  ]
+}