workflow 5.0.0-beta.1 → 5.0.0-beta.2

package/docs/cookbook/integrations/sandbox.mdx

@@ -0,0 +1,128 @@
+---
+title: Sandbox
+description: Orchestrate Vercel Sandbox lifecycle -- creation, code execution, snapshotting -- inside durable workflows.
+type: guide
+summary: Use workflow steps to provision sandboxes, run code, and manage sandbox lifecycle with automatic cleanup on failure.
+related:
+  - /docs/ai/defining-tools
+  - /docs/foundations/errors-and-retries
+  - /docs/api-reference/workflow-ai/durable-agent
+---
+
+[Vercel Sandbox](https://vercel.com/docs/sandbox) provides isolated code execution environments. The `@vercel/sandbox` package implements first-class support for the Workflow SDK -- the `Sandbox` class is serializable, and its methods (`create`, `runCommand`, `destroy`, etc.) implicitly run as steps. This means you can interact with sandboxes directly inside workflow functions without wrapping each operation in a separate `"use step"` function.
+
+## What It Enables
+
+- **Durable sandbox sessions** -- Sandbox provisioning and teardown survive cold starts
+- **Automatic cleanup** -- Saga-style compensation ensures sandboxes are destroyed on failure
+- **Multi-step code execution** -- Run a sequence of commands in the same sandbox with each step logged
+- **Agent-driven sandboxes** -- Give your DurableAgent a tool that spins up sandboxes on demand
+
+## When to Use
+
+Use this integration when your workflow needs to:
+
+- Execute user-provided or AI-generated code safely
+- Run multi-step build/test pipelines in isolated environments
+- Provision temporary environments for interactive sessions
+- Snapshot sandbox state between steps for reproducibility
+
+## Sandbox Lifecycle in a Workflow
+
+Because `@vercel/sandbox` methods are implicit steps, each call is automatically persisted to the event log. If a failure occurs partway through, the workflow replays from where it left off.
+
+```typescript title="workflows/sandbox-pipeline.ts" lineNumbers
+import { Sandbox } from "@vercel/sandbox";
+
+export async function sandboxPipeline(input: {
+  template: string;
+  commands: string[];
+}) {
+  "use workflow";
+
+  const sandbox = await Sandbox.create({ template: input.template }); // [!code highlight]
+
+  try {
+    const results = [];
+    for (const command of input.commands) {
+      const result = await sandbox.runCommand(command); // [!code highlight]
+      results.push(result);
+    }
+    return { status: "completed", results };
+  } catch (error) {
+    await sandbox.destroy(); // [!code highlight]
+    throw error;
+  }
+}
+```
+
+## Sandbox as an Agent Tool
+
+Give a DurableAgent the ability to create and use sandboxes. The agent decides when to spin up a sandbox, what code to run, and when to tear it down. Since sandbox methods are implicit steps, the tool execute functions can call them directly.
+
+```typescript title="workflows/code-agent.ts" lineNumbers
+import { Sandbox } from "@vercel/sandbox";
+import { DurableAgent } from "@workflow/ai/agent";
+import { convertToModelMessages, type UIMessage, type UIMessageChunk } from "ai";
+import { getWritable } from "workflow";
+import z from "zod/v4";
+
+export async function codeAgent(messages: UIMessage[]) {
+  "use workflow";
+
+  let activeSandbox: Sandbox | null = null;
+
+  const agent = new DurableAgent({
+    model: "anthropic/claude-sonnet-4-20250514",
+    instructions:
+      "You are a coding assistant. You can create sandboxes to run code. " +
+      "Always create a sandbox first, then execute code in it. " +
+      "Clean up the sandbox when you are done.",
+    tools: {
+      createSandbox: {
+        description: "Create an isolated sandbox environment for running code",
+        inputSchema: z.object({
+          template: z.string().describe("The sandbox template (e.g., 'node', 'python')"),
+        }),
+        execute: async ({ template }) => {
+          activeSandbox = await Sandbox.create({ template }); // [!code highlight]
+          return { sandboxId: activeSandbox.id };
+        },
+      },
+      executeCode: {
+        description: "Execute a command in the active sandbox",
+        inputSchema: z.object({
+          command: z.string().describe("The command to execute"),
+        }),
+        execute: async ({ command }) => {
+          if (!activeSandbox) throw new Error("No active sandbox");
+          return activeSandbox.runCommand(command); // [!code highlight]
+        },
+      },
+      cleanupSandbox: {
+        description: "Destroy the active sandbox when finished",
+        inputSchema: z.object({}),
+        execute: async () => {
+          if (!activeSandbox) throw new Error("No active sandbox");
+          await activeSandbox.destroy(); // [!code highlight]
+          activeSandbox = null;
+          return { cleaned: true };
+        },
+      },
+    },
+  });
+
+  const result = await agent.stream({
+    messages: await convertToModelMessages(messages),
+    writable: getWritable<UIMessageChunk>(),
+  });
+
+  return { messages: result.messages };
+}
+```
+
+## Saga Pattern for Cleanup
+
+Combine sandbox orchestration with the [saga pattern](/docs/cookbook/common-patterns/saga) to ensure sandboxes are always cleaned up, even when a step in the middle of your pipeline fails.
+
+The example above uses a try/catch around the command execution loop. For more complex pipelines with multiple resources (sandbox + database + external API), push compensation functions onto a stack as shown in the [saga recipe](/docs/cookbook/common-patterns/saga).

package/docs/cookbook/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Cookbook",
+  "defaultOpen": true,
+  "pages": ["common-patterns", "agent-patterns", "integrations", "advanced"]
+}

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

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

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

@@ -141,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 />
 

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/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/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"
+  ]
+}