workflow 5.0.0-beta.9 → 5.0.1

package/docs/ai/defining-tools.mdx

@@ -14,16 +14,15 @@ related:
 
 This page covers the details for some common patterns when defining tools for AI agents using Workflow SDK.
 
-Using DurableAgent, we model most tools as steps. These can be anything from a simple function call to a entire multi-day long workflow.
+Using WorkflowAgent, we model most tools as steps. These can range from a single function call to an entire multi-day workflow.
 
 ## Accessing message context in tools
 
-Just like in regular AI SDK tool definitions, tool in DurableAgent are called with a first argument of the tool's input parameters, and a second argument of the tool call context.
+As with regular AI SDK tool definitions, tools in WorkflowAgent receive the tool's input parameters as the first argument and the tool call context as the second.
 
-When you tool needs access to the full message history, you can access it via the `messages` property of the tool call context:
+When your tool needs access to the full message history, you can access it via the `messages` property of the tool call context:
 
 ```typescript title="tools.ts" lineNumbers
-import { Experimental_Agent as Agent } from "ai";
 import type { ModelMessage } from "ai";
 
 async function getWeather(
@@ -34,9 +33,9 @@ async function getWeather(
 }
 ```
 
-## Writing to Streams
+## Writing to streams
 
-As discussed in [Streaming Updates from Tools](/docs/ai/streaming-updates-from-tools), it's common to use a step just to call `getWritable()` for writing custom data parts to the stream.
+As discussed in [Streaming Updates from Tools](/docs/ai/streaming-updates-from-tools), it's common to use a step only to call `getWritable()` for writing custom data parts to the stream.
 
 This can be made generic, by creating a helper step function to write arbitrary data to the stream:
 
@@ -53,7 +52,7 @@ async function writeToStream(data: any) {
 }
 ```
 
-## Step-Level vs Workflow-Level Tools
+## Step-level vs workflow-level tools
 
 Tools can be implemented either at the step level or the workflow level, with different capabilities and constraints.
 

package/docs/ai/human-in-the-loop.mdx

@@ -19,7 +19,7 @@ Workflow SDK's [webhook](/docs/api-reference/workflow/create-webhook) and [hook]
 
 If you need to react to external events programmatically, see the [hooks](/docs/foundations/hooks) documentation for more information. This part of the guide will focus on the human-in-the-loop pattern, which is a subset of the more general hook pattern.
 
-## How It Works
+## How it works
 
 <Steps>
 
@@ -45,9 +45,9 @@ The workflow receives the approval data and resumes execution.
 
 </Steps>
 
-While this demo will use a client side button for human approval, you could just as easily create a webhook and send the approval link over email or slack to resume the agent.
+While this demo uses a client-side button for human approval, you could instead create a webhook and send the approval link over email or Slack to resume the agent.
 
-## Creating a Booking Approval Tool
+## Creating a booking approval tool
 
 Add a tool that allows the agent to deliberately pause execution until a human approves or rejects a flight booking:
 
@@ -55,7 +55,7 @@ Add a tool that allows the agent to deliberately pause execution until a human a
 
 <Step>
 
-### Define the Hook
+### Define the hook
 
 Create a typed hook with a Zod schema for validation:
 
@@ -78,7 +78,7 @@ export const bookingApprovalHook = defineHook({
 
 <Step>
 
-### Implement the Tool
+### Implement the tool
 
 Create a tool that creates a hook instance using the tool call ID as the token. The UI will use this ID to submit the approval.
 
@@ -126,14 +126,14 @@ export const flightBookingTools = {
 ```
 
 <Callout type="info">
-Note that the `defineHook().create()` function must be called from within a workflow context, not from within a step. This is why `executeBookingApproval` does not have `"use step"` - it runs in the workflow context where hooks are available.
+Call `defineHook().create()` from within a workflow context, not from within a step. `executeBookingApproval` does not have `"use step"` because it runs in the workflow context where hooks are available.
 </Callout>
 
 </Step>
 
 <Step>
 
-### Create the API Route
+### Create the API route
 
 Create a new API endpoint that the UI will call to submit the approval decision:
 
@@ -154,11 +154,15 @@ export async function POST(request: Request) {
 }
 ```
 
+<Callout type="warn">
+This route resumes whichever hook owns `toolCallId`, so anyone who learns the ID can submit a decision. In production, authenticate the request and check that the signed-in user may approve this booking before calling `resume()`. See [Hook and webhook security](/docs/foundations/hooks#security).
+</Callout>
+
 </Step>
 
 <Step>
 
-### Create the Approval Component
+### Create the approval component
 
 Build a new component that reacts to the tool call data, and allows the user to approve or reject the booking:
 
@@ -253,7 +257,7 @@ export function BookingApproval({ toolCallId, input, output }: BookingApprovalPr
 
 <Step>
 
-### Show the Tool Status in the UI
+### Show the tool status in the UI
 
 Use the component we just created to render the tool call and approval controls in your chat interface:
 
@@ -332,9 +336,9 @@ export default function ChatPage() {
 
 </Steps>
 
-## Using Webhooks Directly
+## Using webhooks directly
 
-For simpler cases where you don't need type-safe validation or programmatic resumption, you can use [`createWebhook()`](/docs/api-reference/workflow/create-webhook) directly. This generates a unique URL that can be called to resume the workflow:
+For simpler cases where you don't need type-safe validation or programmatic resumption, you can use [`createWebhook()`](/docs/api-reference/workflow/create-webhook) directly. This generates a unique URL that can be called to resume the workflow. Anyone with the URL can resume it, so avoid this for approvals that need to know who approved, unless you use the incoming payload for authorization. See [Hook and webhook security](/docs/foundations/hooks#security).
 
 ```typescript title="workflows/chat/steps/tools.ts" lineNumbers
 import { createWebhook } from "workflow";
@@ -367,7 +371,7 @@ The webhook URL can be called directly with a POST request containing the approv
 - Payment provider callbacks
 - Email-based approval links
 
-## Related Documentation
+## Related documentation
 
 - [Hooks & Webhooks](/docs/foundations/hooks) - Complete guide to hooks and webhooks
 - [`createWebhook()` API Reference](/docs/api-reference/workflow/create-webhook) - Webhook configuration options

package/docs/ai/index.mdx

@@ -3,6 +3,7 @@ title: Building Durable AI Agents
 description: Build AI agents that survive crashes, scale across requests, and maintain state with durable LLM tool-call loops.
 type: overview
 summary: Convert a basic AI chat app into a durable, resumable agent using Workflow SDK.
+manualCards: true
 related:
   - /docs/foundations/workflows-and-steps
   - /docs/foundations/streaming
@@ -21,7 +22,7 @@ Workflow SDK makes your agents production-ready, by turning them into durable, r
 
 This guide walks you through converting a basic AI chat app into a durable AI agent using Workflow SDK.
 
-## Why Durable Agents?
+## Why durable agents?
 
 Aside from the usual challenges of getting your long-running tasks to be production-ready, building mature AI agents typically requires solving several **additional challenges**:
 
@@ -30,22 +31,22 @@ Aside from the usual challenges of getting your long-running tasks to be product
 - **Resumability**: Resuming streams requires not just storing your messages, but also storing streams, and piping them across services.
 - **Human-in-the-loop**: Your client, API, and async job orchestration need to work together to create, track, route to, and display human approval requests, or similar webhook operations.
 
-Workflow SDK provides all of these capabilities out of the box. Your agent becomes a workflow, your tools become steps, and the framework handles interplay with your existing infrastructure.
+Workflow SDK provides all of these capabilities without additional infrastructure. Your agent becomes a workflow, your tools become steps, and the framework handles interplay with your existing infrastructure.
 
-## Getting Started
+## Getting started
 
 To make an Agent durable, we first need an Agent, which we'll be setting up here. If you already have an app you'd like to follow along with, you can skip this section.
 
-For our example, we'll need an app with a simple chat interface and an API route calling an LLM, so that we can add Workflow SDK to it. We'll use the [Flight Booking Agent](https://github.com/vercel/workflow-examples/tree/main/flight-booking-app) example as a starting point, which comes with a chat interface built using Next.js, AI SDK, and Shadcn UI.
+For our example, we'll need an app with a basic chat interface and an API route calling an LLM, so that we can add Workflow SDK to it. We'll use the [Flight Booking Agent](https://github.com/vercel/workflow-examples/tree/main/flight-booking-app) example as a starting point, which comes with a chat interface built using Next.js, AI SDK, and Shadcn UI.
 
 <Steps>
 
 <Step>
 ### Clone example app
 
-We'll need an app with a simple chat interface and an API route calling an LLM, so that we can add Workflow SDK to it. For the follow-along steps, we'll use the [Flight Booking Agent](https://github.com/vercel/workflow-examples/tree/main/flight-booking-app) example as a starting point, which comes with a chat interface built using Next.js, AI SDK, and Shadcn UI.
+We'll need an app with a basic chat interface and an API route calling an LLM, so that we can add Workflow SDK to it. For the follow-along steps, we'll use the [Flight Booking Agent](https://github.com/vercel/workflow-examples/tree/main/flight-booking-app) example as a starting point, which comes with a chat interface built using Next.js, AI SDK, and Shadcn UI.
 
-If you have your own project, you can skip this step, and simply apply the changes of the following steps to your own project.
+If you have your own project, skip this step and apply the changes in the following steps to your project.
 
 ```bash
 git clone https://github.com/vercel/workflow-examples -b plain-ai-sdk
@@ -56,55 +57,49 @@ cd workflow-examples/flight-booking-app
 
 <Step>
 
-### Set up API keys
+### Configure model access
 
-In order to connect to an LLM, we'll need to set up an API key. The easiest way to do this is to use Vercel Gateway (works with all providers at zero markup), or you can configure a custom provider.
-<Tabs items={['Gateway', 'Custom Provider']}>
+<Tabs items={['AI Gateway', 'Provider package']}>
 
-<Tab value="Gateway">
+<Tab value="AI Gateway">
 
-Get a Gateway API key from the [Vercel Gateway](https://vercel.com/docs/gateway/api-reference/overview) page.
+AI SDK uses [Vercel AI Gateway](https://vercel.com/docs/ai-gateway) as its default global provider, so plain `"provider/model"` strings need no provider-specific package. Vercel deployments authenticate with OIDC automatically. For local development, link the project and pull a short-lived OIDC token:
 
-Then add it to your `.env.local` file:
-
-```bash title=".env.local" lineNumbers
-GATEWAY_API_KEY=...
+```bash
+vercel link
+vercel env pull .env.local
 ```
 
+You can alternatively set `AI_GATEWAY_API_KEY` from the [AI Gateway authentication](https://vercel.com/docs/ai-gateway/authentication) page.
+
 </Tab>
 
-<Tab value="Custom Provider">
+<Tab value="Provider package">
 
-This is an example of how to use the OpenAI provider for AI SDK. For details on other providers and more details, see the [AI SDK provider guide](https://ai-sdk.dev/providers/ai-sdk-providers).
+`WorkflowAgent` accepts any AI SDK provider. To use OpenAI, install its provider package:
 
 ```package-install
 npm i @ai-sdk/openai
 ```
 
-Set your OpenAI API key in your environment variables:
+Set the provider's API key:
 
 ```bash title=".env.local" lineNumbers
 OPENAI_API_KEY=...
 ```
 
-Then modify your API endpoint to use the OpenAI provider:
+Then construct the model with the provider package:
 
-{/* @skip-typecheck: incomplete code sample */}
-```typescript title="app/api/chat/route.ts" lineNumbers
-// ...
-import { openai } from "@workflow/ai/openai"; // [!code highlight]
+```typescript
+import { openai } from "@ai-sdk/openai";
 
-export async function POST(req: Request) {
-  // ...
-  const agent = new Agent({
-    // This uses the OPENAI_API_KEY environment variable by default, but you
-    // can also pass { apiKey: string } as an option.
-    model: openai("gpt-5.1"), // [!code highlight]
-    // ...
-  });
+const model = openai("gpt-5.6-sol");
 ```
 
+See the [AI SDK provider guide](https://ai-sdk.dev/providers/ai-sdk-providers) for Anthropic, Google, Amazon Bedrock, and other providers.
+
 </Tab>
+
 </Tabs>
 </Step>
 
@@ -112,15 +107,15 @@ export async function POST(req: Request) {
 
 ### Get familiar with the code
 
-Let's take a moment to see what we're working with. Run the app with `npm run dev` and open [http://localhost:3000](http://localhost:3000) in your browser. You should see a simple chat interface to play with. Go ahead and give it a try.
+Run the app with `npm run dev` and open [http://localhost:3000](http://localhost:3000) in your browser. You should see a basic chat interface to test.
 
-The core code that makes all of this happen is quite simple. Here's a breakdown of the main parts. Note that there's no changes needed here, we're simply taking a look at the code to understand what's happening.
+The following sections break down the core code. You don't need to make changes yet.
 
 <Tabs items={['API Route', 'Tools', 'Client']}>
 
 <Tab value="API Route">
 
-Our API route makes a simple call to [AI SDK's `ToolLoopAgent` class](https://ai-sdk.dev/docs/agents/overview), which encapsulates the LLM call, tool execution loop, and stopping conditions on top of [AI SDK's `streamText` function](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text#streamtext). This is also where we pass tools to the agent.
+Our API route calls [AI SDK's `ToolLoopAgent` class](https://ai-sdk.dev/docs/agents/overview), which encapsulates the LLM call, tool execution loop, and stopping conditions on top of [AI SDK's `streamText` function](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text#streamtext). This is also where we pass tools to the agent.
 
 ```typescript title="app/api/chat/route.ts" lineNumbers
 import { ToolLoopAgent } from "ai";
@@ -130,7 +125,7 @@ import { convertToModelMessages, createUIMessageStreamResponse } from "ai";
 export async function POST(req: Request) {
   const { messages }: { messages: UIMessage[] } = await req.json();
   const agent = new ToolLoopAgent({ // [!code highlight]
-    model: "bedrock/claude-4-5-haiku-20251001-v1",
+    model: "spacexai/grok-4.6",
     instructions: FLIGHT_ASSISTANT_PROMPT,
     tools: flightBookingTools,
   });
@@ -169,7 +164,7 @@ async function searchFlights({ from, to, date }: { from: string; to: string; dat
 
 <Tab value="Client">
 
-Our `ChatPage` component has a lot of logic for nicely displaying the chat messages, but at it's core, it's simply managing input/output for the [`useChat` hook](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#usechat) from AI SDK.
+Our `ChatPage` component contains logic for displaying chat messages, but its core responsibility is managing input and output for the [`useChat` hook](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#usechat) from AI SDK.
 
 ```typescript title="app/chat.tsx" lineNumbers
 "use client";
@@ -227,12 +222,12 @@ Now that we have a basic agent using AI SDK, we can modify it to make it durable
 <Steps>
 <Step>
 
-### Install Dependencies
+### Install dependencies
 
 Add the Workflow SDK packages to your project:
 
 ```package-install
-npm i workflow @workflow/ai
+npm i workflow @ai-sdk/workflow
 ```
 
 and extend the Next.js config to transform your workflow code (see [Getting Started](/docs/getting-started/next) for more details).
@@ -252,68 +247,67 @@ export default withWorkflow(nextConfig);
 
 <Step>
 
-### Create a Workflow Function
+### Create a workflow function
 
 Move the agent logic into a separate function, which will serve as our workflow definition.
 
-{/* @skip-typecheck: Shows two mutually exclusive model options */}
 ```typescript title="workflows/chat/workflow.ts" lineNumbers
-import { DurableAgent } from "@workflow/ai/agent"; // [!code highlight]
+import { WorkflowAgent, type ModelCallStreamPart } from "@ai-sdk/workflow"; // [!code highlight]
 import { getWritable } from "workflow"; // [!code highlight]
-import { tools } from "@/ai/tools";
-import { openai } from "@workflow/ai/openai";
-import type { ModelMessage, UIMessageChunk } from "ai";
+import { flightBookingTools, FLIGHT_ASSISTANT_PROMPT } from "@/ai/tools";
+import { convertToModelMessages, type UIMessage } from "ai";
 
-export async function chatWorkflow(messages: ModelMessage[]) {
+export async function chatWorkflow(messages: UIMessage[]) {
   "use workflow"; // [!code highlight]
 
-  const writable = getWritable<UIMessageChunk>(); // [!code highlight]
-
-  const agent = new DurableAgent({ // [!code highlight]
-
-    // If using AI Gateway, just specify the model name as a string:
-    model: "bedrock/claude-4-5-haiku-20251001-v1", // [!code highlight]
-
-    // ELSE if using a custom provider, pass the provider call as an argument:
-    model: openai("gpt-5.1"), // [!code highlight]
+  const writable = getWritable<ModelCallStreamPart>(); // [!code highlight]
 
+  const agent = new WorkflowAgent({ // [!code highlight]
+    // Plain model strings use Vercel AI Gateway.
+    model: "spacexai/grok-4.6", // [!code highlight]
     instructions: FLIGHT_ASSISTANT_PROMPT,
     tools: flightBookingTools,
   });
 
+  const modelMessages = await convertToModelMessages(messages); // [!code highlight]
+
   await agent.stream({ // [!code highlight]
-    messages,
+    messages: modelMessages,
     writable,
   });
 }
 ```
 
+<Callout type="info">
+`WorkflowAgent` accepts any AI SDK provider. Import the provider and pass its model instance, for example `model: openai("gpt-5.6-sol")` from `@ai-sdk/openai`. The rest of the integration is unchanged.
+</Callout>
+
 Key changes:
 
 - Add the `"use workflow"` directive to mark our Agent as a workflow function
-- Replaced `Agent` with [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) from `@workflow/ai/agent`. This ensures that all calls to the LLM are executed as "steps", and results are aggregated within the workflow context (see [Workflows and Steps](/docs/foundations/workflows-and-steps) for more details on how workflows/steps are defined).
-- Use [`getWritable()`](/docs/api-reference/workflow/get-writable) to get a stream for agent output. This stream is persistent, and API endpoints can read from a run's stream at any time.
+- Replace the in-memory agent with [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) from `@ai-sdk/workflow`. This runs the agent loop inside a workflow, persists state across step boundaries, and lets tool executions marked with `"use step"` retry automatically.
+- Convert AI SDK `UIMessage` values to model messages inside the workflow before calling `agent.stream()`.
+- Use [`getWritable()`](/docs/api-reference/workflow/get-writable) to get a stream for agent output. `WorkflowAgent` writes `ModelCallStreamPart` chunks to this persistent stream, and API endpoints can read from a run's stream at any time.
 </Step>
 
 <Step>
-### Update the API Route
+### Update the API route
 
 Remove the agent call that we just extracted, and replace it with a call to `start()` to run the workflow:
 
 ```typescript title="app/api/chat/route.ts" lineNumbers
-import type { UIMessage } from "ai";
-import { convertToModelMessages, createUIMessageStreamResponse } from "ai";
+import { createModelCallToUIChunkTransform } from "@ai-sdk/workflow";
+import { createUIMessageStreamResponse, type UIMessage } from "ai";
 import { start } from "workflow/api";
 import { chatWorkflow } from "@/workflows/chat/workflow";
 
 export async function POST(req: Request) {
   const { messages }: { messages: UIMessage[] } = await req.json();
-  const modelMessages = await convertToModelMessages(messages);
 
-  const run = await start(chatWorkflow, [modelMessages]); // [!code highlight]
+  const run = await start(chatWorkflow, [messages]); // [!code highlight]
 
   return createUIMessageStreamResponse({
-    stream: run.readable, // [!code highlight]
+    stream: run.readable.pipeThrough(createModelCallToUIChunkTransform()), // [!code highlight]
   });
 }
 ```
@@ -321,12 +315,13 @@ export async function POST(req: Request) {
 Key changes:
 
 - Call `start()` to run the workflow function. This returns a `Run` object, which contains the run ID and the readable stream (see [Starting Workflows](/docs/foundations/starting-workflows) for more details on the `Run` object).
-- Pass the `writable` to `agent.stream()` instead of returning a stream directly, ensuring all the Agent output is written to to the run's stream.
+- Pass the `writable` to `agent.stream()` instead of returning a stream directly, ensuring all the Agent output is written to the run's stream.
+- Pipe the readable stream through `createModelCallToUIChunkTransform()` so the raw model-call chunks become AI SDK UI message chunks before they are returned to the client.
 
 </Step>
 
 <Step>
-### Convert Tools to Steps
+### Convert tools to steps
 
 Mark all tool definitions with `"use step"` to make them durable. This enables automatic retries and observability for each tool call:
 
@@ -378,14 +373,14 @@ export async function checkBaggageAllowance(
 
 With `"use step"`:
 
-- The tool execution runs in a separate step with full Node.js access. In production, each step is executed in a separate worker process, which scales automatically with your workload.
+- The tool execution runs as a durable step with full Node.js access. The combined runtime may execute it inline in the flow request or resume it through the workflow queue, and can scale queued work with your workload.
 - Failed tool calls are automatically retried (up to 3 times by default). See [Errors and Retries](/docs/foundations/errors-and-retries) for more details.
 - Each tool execution appears as a discrete step in observability tools. See [Observability](/docs/observability) for more details.
 </Step>
 
 </Steps>
 
-That's all you need to do to convert your basic AI SDK agent into a durable agent. If you run your development server, and send a chat message, you should see your agent respond just as before, but now with added durability and observability.
+Your basic AI SDK agent is now durable. Run your development server and send a chat message. The agent should respond as before, with added durability and observability.
 
 ## Observability
 
@@ -397,9 +392,9 @@ npx workflow web
 
 This opens a local dashboard showing all workflow runs and their status, as well as a trace viewer to inspect the workflow in detail, including retry attempts, and the data being passed between steps.
 
-## Next Steps
+## Next steps
 
-Now that you have a basic durable agent, it's a only a short step to add these additional features:
+Now that you have a basic durable agent, it's only a short step to add these additional features:
 
 <Cards>
   <Card title="Streaming Updates from Tools" href="/docs/ai/streaming-updates-from-tools">
@@ -416,14 +411,14 @@ Now that you have a basic durable agent, it's a only a short step to add these a
   </Card>
 </Cards>
 
-## Complete Example
+## Complete example
 
 A complete example that includes all of the above, plus all of the "next steps" features is available on the main branch of the [Flight Booking Agent](https://github.com/vercel/workflow-examples/tree/main/flight-booking-app) example.
 
-## Related Documentation
+## Related documentation
 
 - [Tools](/docs/ai/defining-tools) - Patterns for defining tools for your agent
-- [`DurableAgent` API Reference](/docs/api-reference/workflow-ai/durable-agent) - Full API documentation
+- [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) - AI SDK API for durable, resumable agents
 - [Workflows and Steps](/docs/foundations/workflows-and-steps) - Core concepts
 - [Streaming](/docs/foundations/streaming) - In-depth streaming guide
 - [Errors and Retries](/docs/foundations/errors-and-retries) - Error handling patterns