Cookbook

Best-practice workflow patterns with copy-paste code examples.

Use these workflow patterns and copy-paste code examples to implement common use cases.

Agent patterns

  • WorkflowAgent: Build durable, resumable AI agents with AI SDK's WorkflowAgent.
  • Human-in-the-Loop: Pause an agent for human approval, then resume based on the decision.
  • Agent Cancellation: Stop a running agent immediately via run.cancel() or gracefully via a hook + Promise.race.

Common patterns

  • Sequential & Parallel Execution: Compose steps with await, Promise.all, and Promise.race against durable sleeps and webhooks.
  • Workflow Composition: Call workflows from other workflows by direct await or background spawn via start().
  • Saga: Coordinate multi-step transactions with automatic rollback when a step fails.
  • Batching: Process large collections in parallel batches with failure isolation.
  • Rate Limiting: Handle 429 responses and transient failures with RetryableError and backoff.
  • Scheduling: Use durable sleep to schedule actions minutes, hours, or weeks ahead.
  • Timeouts: Add deadlines to slow steps, hooks, and webhooks by racing them against a durable sleep.
  • Idempotency: Ensure side effects and duplicate starts are safe to retry.
  • Webhooks: Receive HTTP callbacks from external services and process them durably.

Integrations

  • AI SDK: Use streamText() directly inside a workflow for lower-level control over model calls and tool execution.
  • Chat SDK: Build durable chat sessions with workflow persistence and AI SDK chat primitives.
  • Sandbox: Orchestrate Vercel Sandbox lifecycle inside durable workflows.

Advanced

  • Child Workflows: Spawn and orchestrate child workflows from a parent.
  • Distributed Abort Controller: Build a cross-process abort controller using workflow streams and hooks.
  • Upgrading Workflows: Identify a clean upgrade point in a long-running workflow and spawn a fresh run on the latest deployment carrying state forward.
  • Serializable Steps: Wrap non-serializable third-party objects so they cross the workflow boundary.
  • Publishing Libraries: Ship npm packages that export reusable workflow functions.