workflow 5.0.0-beta.5 → 5.0.0-beta.51

package/docs/api-reference/workflow/get-writable.mdx

@@ -47,7 +47,7 @@ async function writeToStream(writable: WritableStream) {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -69,7 +69,7 @@ export default getWritable;`}
 
 Returns a `WritableStream<W>` where `W` is the type of data you plan to write to the stream.
 
-## Good to Know
+## Good to know
 
 - **Workflow functions can only obtain the stream** - Call `getWritable()` in a workflow to get the stream reference, but you cannot call methods like `getWriter()`, `write()`, or `close()` directly in the workflow context.
 - **Step functions can interact with streams** - Steps can receive the stream as an argument or call `getWritable()` directly, and they can freely interact with it (write, close, etc.).
@@ -81,9 +81,9 @@ Returns a `WritableStream<W>` where `W` is the type of data you plan to write to
 
 ## Examples
 
-### Basic Text Streaming
+### Basic text streaming
 
-Here's a simple example streaming text data:
+This example streams text data:
 
 ```typescript lineNumbers
 import { sleep, getWritable } from "workflow";
@@ -118,7 +118,7 @@ async function stepCloseOutputStream(writable: WritableStream) {
 }
 ```
 
-### Calling `getWritable()` Inside Steps
+### Calling `getWritable()` inside steps
 
 You can also call `getWritable()` directly inside step functions without passing it as a parameter:
 
@@ -157,7 +157,7 @@ async function stepCloseOutputStreamInside() {
 }
 ```
 
-### Using Namespaced Streams in Steps
+### Using namespaced streams in steps
 
 You can also use namespaced streams when calling `getWritable()` from steps:
 
@@ -201,7 +201,7 @@ async function closeStreams() {
 }
 ```
 
-### Advanced Chat Streaming
+### Advanced chat streaming
 
 Here's a more complex example showing how you might stream AI chat responses:
 

package/docs/api-reference/workflow/index.mdx

@@ -47,9 +47,12 @@ Workflow SDK contains the following functions you can use inside your workflow f
     <Card href="/docs/api-reference/workflow/get-writable" title="getWritable()">
         Access the current workflow run's default stream.
     </Card>
+    <Card href="/docs/api-reference/workflow/set-attributes" title="setAttributes()">
+        Attach string metadata to the current workflow run.
+    </Card>
 </Cards>
 
-## Error Classes
+## Error classes
 
 Workflow SDK includes error classes that can be thrown in a workflow or step to change the error exit strategy of a workflow.
 

package/docs/api-reference/workflow/retryable-error.mdx

@@ -31,7 +31,7 @@ async function retryStep() {
 The difference between `Error` and `RetryableError` may not be entirely obvious, since when both are thrown, they both retry. The difference is that `RetryableError` has an additional configurable `retryAfter` parameter.
 </Callout>
 
-## API Signature
+## API signature
 
 ### Parameters
 

package/docs/api-reference/workflow/set-attributes.mdx

@@ -0,0 +1,61 @@
+---
+title: setAttributes
+description: Attach string metadata to workflow run for observability.
+type: reference
+summary: Use setAttributes inside a workflow or step function to set run attributes.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/observability/attributes
+  - /docs/api-reference/workflow/fatal-error
+---
+
+Attaches string metadata to the current workflow run.
+
+```typescript lineNumbers
+import { setAttributes } from "workflow"
+
+export async function orderWorkflow(orderId: string) {
+  "use workflow"
+
+  await setAttributes({
+    phase: "received",
+    orderId,
+  })
+}
+```
+
+## API signature
+
+### Parameters
+
+<TSDoc
+definition={`
+import { setAttributes } from "workflow";
+export default setAttributes;`}
+showSections={['parameters']}
+/>
+
+## Usage
+
+Call `setAttributes` from a `"use workflow"` function or a `"use step"` function. Calling it from plain application code is not supported because there is no active workflow run.
+
+Attribute values must be strings. Pass `undefined` to remove an attribute:
+
+```typescript lineNumbers
+import { setAttributes } from "workflow"
+
+export async function cleanupAttributes() {
+  "use workflow"
+
+  await setAttributes({ staleKey: undefined })
+}
+```
+
+Attribute keys must be 1-256 characters, values must be strings up to 256 bytes, and each run can have up to 64 attributes. Keys that start with `$` are reserved for framework and library code.
+
+Validation errors throw [`FatalError`](/docs/api-reference/workflow/fatal-error) and fail the run before an attribute write is attempted.
+
+Calls from both workflow and step bodies append a native `attr_set` event, which the World materializes onto `run.attributes`. Workflow-originated events record a workflow writer; step-originated events record the originating step ID and attempt.
+
+Native attributes require spec version 4 or later. Step-body storage errors throw from `setAttributes`; catch them inside the step if the write should be best-effort. Workflow-body writes are committed when the workflow suspends: transient storage errors are retried with the suspension, while a write the World rejects as invalid (such as exceeding the per-run attribute cap across multiple calls) fails the run with the validation error.

package/docs/api-reference/workflow/sleep.mdx

@@ -14,7 +14,7 @@ Suspends a workflow for a specified duration or until an end date without consum
 This is useful when you want to resume a workflow after some duration or date.
 
 <Callout>
-`sleep` is a *special* type of step function and should be called directly inside workflow functions.
+`sleep` is a built-in workflow runtime function (backed by a timer event in the event log, not a step) and should be called directly inside workflow functions.
 </Callout>
 
 ```typescript lineNumbers
@@ -26,7 +26,7 @@ async function testWorkflow() {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -39,7 +39,7 @@ showSections={['parameters']}
 
 ## Examples
 
-### Sleeping With a Duration
+### Sleeping with a duration
 
 You can specify a duration for `sleep` to suspend the workflow for a fixed amount of time.
 
@@ -52,7 +52,7 @@ async function testWorkflow() {
 }
 ```
 
-### Sleeping Until an End Date
+### Sleeping until an end date
 
 You can specify a future `Date` object for `sleep` to suspend the workflow until a specific date.
 

package/docs/api-reference/workflow-ai/durable-agent.mdx

@@ -1,61 +1,23 @@
 ---
 title: DurableAgent
-description: Create AI agents that maintain state, call tools, and handle interruptions gracefully.
+description: Deprecated DurableAgent API reference; use WorkflowAgent for new durable agents.
 type: reference
-summary: Use DurableAgent to build AI agents that maintain state across steps and survive interruptions.
+summary: "Deprecated: use AI SDK's WorkflowAgent instead of DurableAgent."
 prerequisites:
   - /docs/ai
 related:
   - /docs/ai/defining-tools
 ---
 
-The `DurableAgent` class enables you to create AI-powered agents that can maintain state across workflow steps, call tools, and gracefully handle interruptions and resumptions.
-
-Tool calls can be implemented as workflow steps for automatic retries, or as regular workflow-level logic utilizing core library features such as [`sleep()`](/docs/api-reference/workflow/sleep) and [Hooks](/docs/foundations/hooks).
-
-```typescript lineNumbers
-import { DurableAgent } from "@workflow/ai/agent";
-import { getWritable } from "workflow";
-import { z } from "zod";
-import type { UIMessageChunk } from "ai";
-
-async function getWeather({ city }: { city: string }) {
-  "use step";
-
-  return `Weather in ${city} is sunny`;
-}
-
-async function myAgent() {
-  "use workflow";
-
-  const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
-    instructions: "You are a helpful weather assistant.",
-    temperature: 0.7,
-    tools: {
-      getWeather: {
-        description: "Get weather for a city",
-        inputSchema: z.object({ city: z.string() }),
-        execute: getWeather,
-      },
-    },
-  });
-
-  // The agent will stream its output to the workflow
-  // run's default output stream
-  const writable = getWritable<UIMessageChunk>();
+<Callout type="warn">
+`DurableAgent` is deprecated. Use AI SDK's [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) for new durable agents. See the [migration guide](https://ai-sdk.dev/v7/docs/agents/workflow-agent#migrating-from-durableagent).
+</Callout>
 
-  const result = await agent.stream({
-    messages: [{ role: "user", content: "How is the weather in San Francisco?" }],
-    writable,
-  });
+This reference is kept for existing applications that still import `DurableAgent` from `@workflow/ai/agent`. Do not use `DurableAgent` for new code.
 
-  // result contains messages, steps, and optional structured output
-  console.log(result.messages);
-}
-```
+For current examples and implementation guidance, see AI SDK's [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) docs. For legacy code, the API surface below documents the existing `DurableAgent` exports.
 
-## API Signature
+## API signature
 
 ### Class
 
@@ -163,7 +125,7 @@ import type { StreamTextOnAbortCallback } from "@workflow/ai/agent";
 export default StreamTextOnAbortCallback;`}
 />
 
-### Advanced Types
+### Advanced types
 
 #### ToolCallRepairFunction
 
@@ -195,30 +157,30 @@ import type { OutputSpecification } from "@workflow/ai/agent";
 export default OutputSpecification;`}
 />
 
-## Key Features
+## Key features
 
-- **Durable Execution**: Agents can be interrupted and resumed without losing state
-- **Flexible Tool Implementation**: Tools can be implemented as workflow steps for automatic retries, or as regular workflow-level logic
-- **Stream Processing**: Handles streaming responses and tool calls in a structured way
-- **Workflow Native**: Fully integrated with Workflow SDK for production-grade reliability
-- **AI SDK Parity**: Supports the same options as AI SDK's `streamText` including generation settings, callbacks, and structured output
+- **Durable execution**: Agents can be interrupted and resumed without losing state.
+- **Flexible tool implementation**: Tools can be implemented as workflow steps for automatic retries or as regular workflow-level logic.
+- **Stream processing**: Handles streaming responses and tool calls in a structured way.
+- **Workflow native**: Fully integrated with Workflow SDK for production reliability.
+- **AI SDK parity**: Supports the same options as AI SDK's `streamText`, including generation settings, callbacks, and structured output.
 
-## Good to Know
+## Good to know
 
-- Tools can be implemented as workflow steps (using `"use step"` for automatic retries), or as regular workflow-level logic
-- Tools can use core library features like `sleep()` and Hooks within their `execute` functions
-- The agent processes tool calls iteratively until completion or `maxSteps` is reached
-- **Default `maxSteps` is unlimited** - set a value to limit the number of LLM calls
-- The `stream()` method returns `{ messages, steps, toolCalls, toolResults, experimental_output, uiMessages }` containing the full conversation history, step details, tool call details, optional structured output, and optionally accumulated UI messages
-- Use `collectUIMessages: true` to accumulate `UIMessage[]` during streaming, useful for persisting conversation state without re-reading the stream
-- The `prepareStep` callback runs before each step and can modify model, messages, generation settings, tool choice, and context
-- Generation settings (temperature, maxOutputTokens, etc.) can be set on the constructor and overridden per-stream call
-- Use `activeTools` to limit which tools are available for a specific stream call
-- The `onFinish` callback is called when all steps complete; `onAbort` is called if aborted
+- Tools can be implemented as workflow steps (using `"use step"` for automatic retries) or as regular workflow-level logic.
+- Tools can use core library features like `sleep()` and hooks within their `execute` functions.
+- The agent processes tool calls iteratively until completion or until `maxSteps` is reached.
+- **Default `maxSteps` is unlimited**: Set a value to limit the number of large language model (LLM) calls.
+- The `stream()` method returns `{ messages, steps, toolCalls, toolResults, experimental_output, uiMessages }` containing the full conversation history, step details, tool call details, optional structured output, and optionally accumulated user interface (UI) messages.
+- Use `collectUIMessages: true` to accumulate `UIMessage[]` during streaming, which is useful for persisting conversation state without re-reading the stream.
+- The `prepareStep` callback runs before each step and can modify the model, messages, generation settings, tool choice, and context.
+- Generation settings (`temperature`, `maxOutputTokens`, and others) can be set on the constructor and overridden per-stream call.
+- Use `activeTools` to limit which tools are available for a specific stream call.
+- The `onFinish` callback is called when all steps complete; `onAbort` is called if aborted.
 
 ## Examples
 
-### Basic Agent with Tools
+### Basic agent with tools
 
 ```typescript
 import { DurableAgent } from "@workflow/ai/agent";
@@ -237,7 +199,7 @@ async function weatherAgentWorkflow(userQuery: string) {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     tools: {
       getWeather: {
         description: "Get current weather for a location",
@@ -260,7 +222,7 @@ async function weatherAgentWorkflow(userQuery: string) {
 }
 ```
 
-### Multiple Tools
+### Multiple tools
 
 ```typescript
 import { DurableAgent } from "@workflow/ai/agent";
@@ -282,7 +244,7 @@ async function multiToolAgentWorkflow(userQuery: string) {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     tools: {
       getWeather: {
         description: "Get weather for a location",
@@ -309,7 +271,7 @@ async function multiToolAgentWorkflow(userQuery: string) {
 }
 ```
 
-### Multi-turn Conversation
+### Multi-turn conversation
 
 ```typescript
 import { DurableAgent } from "@workflow/ai/agent";
@@ -327,7 +289,7 @@ async function multiTurnAgentWorkflow() {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     tools: {
       searchProducts: {
         description: "Search for products",
@@ -363,7 +325,7 @@ async function multiTurnAgentWorkflow() {
 }
 ```
 
-### Tools with Workflow Library Features
+### Tools with Workflow library features
 
 ```typescript
 import { DurableAgent } from "@workflow/ai/agent";
@@ -385,7 +347,7 @@ async function requestApproval({ message }: { message: string }) {
   // Note: No "use step" for this tool call either,
   // since hooks are awaited at the workflow level
 
-  // Utilize a Hook for Human-in-the-loop approval
+  // Use a Hook for Human-in-the-loop approval
   const hook = approvalHook.create({
     metadata: { message }
   });
@@ -406,7 +368,7 @@ async function agentWithLibraryFeaturesWorkflow(userRequest: string) {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     tools: {
       scheduleTask: {
         description: "Pause the workflow for the specified number of seconds",
@@ -430,7 +392,7 @@ async function agentWithLibraryFeaturesWorkflow(userRequest: string) {
 }
 ```
 
-### Dynamic Context with prepareStep
+### Dynamic context with prepareStep
 
 Use `prepareStep` to modify settings before each step in the agent loop:
 
@@ -443,7 +405,7 @@ async function agentWithPrepareStep(userMessage: string) {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "openai/gpt-4.1-mini", // Default model
+    model: "spacexai/grok-4.6", // Default model
     instructions: "You are a helpful assistant.",
   });
 
@@ -474,7 +436,7 @@ async function agentWithPrepareStep(userMessage: string) {
 }
 ```
 
-### Message Injection with prepareStep
+### Message injection with prepareStep
 
 Inject messages from external sources (like hooks) before each LLM call:
 
@@ -497,7 +459,7 @@ async function agentWithMessageQueue(initialMessage: string) {
   });
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     instructions: "You are a helpful assistant.",
   });
 
@@ -524,7 +486,7 @@ async function agentWithMessageQueue(initialMessage: string) {
 }
 ```
 
-### Generation Settings
+### Generation settings
 
 Configure model generation parameters at the constructor or stream level:
 
@@ -538,7 +500,7 @@ async function agentWithGenerationSettings() {
 
   // Set default generation settings in constructor
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     temperature: 0.7,
     maxOutputTokens: 2000,
     topP: 0.9,
@@ -562,7 +524,7 @@ async function agentWithGenerationSettings() {
 }
 ```
 
-### Limiting Steps with maxSteps
+### Limiting steps with maxSteps
 
 By default, the agent loops until completion. Use `maxSteps` to limit the number of LLM calls:
 
@@ -586,7 +548,7 @@ async function multiStepAgent() {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     tools: {
       searchWeb: {
         description: "Search the web for information",
@@ -613,7 +575,7 @@ async function multiStepAgent() {
 }
 ```
 
-### Callbacks for Monitoring
+### Callbacks for monitoring
 
 Use callbacks to monitor streaming progress, handle errors, and react to completion:
 
@@ -626,7 +588,7 @@ async function agentWithCallbacks() {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
   });
 
   await agent.stream({
@@ -654,7 +616,7 @@ async function agentWithCallbacks() {
 }
 ```
 
-### Structured Output
+### Structured output
 
 Parse structured data from the LLM response using `Output.object`:
 
@@ -668,7 +630,7 @@ async function agentWithStructuredOutput() {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
   });
 
   const result = await agent.stream({
@@ -689,7 +651,7 @@ async function agentWithStructuredOutput() {
 }
 ```
 
-### Tool Choice Control
+### Tool choice control
 
 Control when and which tools the model can use:
 
@@ -703,7 +665,7 @@ async function agentWithToolChoice() {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     tools: {
       calculator: {
         description: "Perform calculations",
@@ -752,7 +714,7 @@ async function agentWithToolChoice() {
 }
 ```
 
-### Passing Context to Tools
+### Passing context to tools
 
 Use `experimental_context` to pass shared context to tool executions:
 
@@ -771,7 +733,7 @@ async function agentWithContext(userId: string) {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     tools: {
       getUserData: {
         description: "Get user data",
@@ -796,7 +758,7 @@ async function agentWithContext(userId: string) {
 }
 ```
 
-### Collecting UI Messages
+### Collecting UI messages
 
 Use `collectUIMessages` to accumulate `UIMessage[]` during streaming. This is useful when you need to persist the conversation without re-reading the run's output stream:
 
@@ -809,7 +771,7 @@ async function agentWithUIMessages(userMessage: string) {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     instructions: "You are a helpful assistant.",
   });
 
@@ -838,7 +800,7 @@ async function saveConversation(messages: UIMessage[]) {
 The `uiMessages` property is only available when `collectUIMessages` is set to `true`. When disabled, `uiMessages` is `undefined`.
 </Callout>
 
-### Machine-Readable Tool Results
+### Machine-readable tool results
 
 `stream()` returns tool call information you can inspect programmatically. Compare `toolCalls` with `toolResults` to find unresolved tool calls that need client-side handling:
 
@@ -857,7 +819,7 @@ async function agentWithToolInspection(userMessage: string) {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
     tools: {
       checkOrderStatus: {
         description: "Check order status",
@@ -895,7 +857,7 @@ async function agentWithToolInspection(userMessage: string) {
 `toolCalls` and `toolResults` reflect the *last step* of the agent loop. Tools without an `execute` function will appear in `toolCalls` but not in `toolResults`, which is how you detect calls that need client-side handling.
 </Callout>
 
-### Aborting Long-Running Streams
+### Aborting long-running streams
 
 Use `timeout` to abort a stream automatically after a fixed duration:
 
@@ -912,7 +874,7 @@ async function agentWithTimeout(userMessage: string) {
   "use workflow";
 
   const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
+    model: "spacexai/grok-4.6",
   });
 
   await agent.stream({
@@ -923,10 +885,10 @@ async function agentWithTimeout(userMessage: string) {
 }
 ```
 
-## See Also
+## See also
 
-- [Building Durable AI Agents](/docs/ai) - Complete guide to creating durable agents
-- [Queueing User Messages](/docs/ai/message-queueing) - Using prepareStep for message injection
-- [WorkflowChatTransport](/docs/api-reference/workflow-ai/workflow-chat-transport) - Transport layer for AI SDK streams
-- [Workflows and Steps](/docs/foundations/workflows-and-steps) - Understanding workflow fundamentals
-- [AI SDK Loop Control](https://ai-sdk.dev/docs/agents/loop-control) - AI SDK's agent loop control patterns
+- [Building Durable AI Agents](/docs/ai): Complete guide to creating durable agents
+- [Queueing User Messages](/docs/ai/message-queueing): Using `prepareStep` for message injection
+- [WorkflowChatTransport](/docs/api-reference/workflow-ai/workflow-chat-transport): Transport layer for AI SDK streams
+- [Workflows and Steps](/docs/foundations/workflows-and-steps): Understanding workflow fundamentals
+- [AI SDK Loop Control](https://ai-sdk.dev/docs/agents/loop-control): AI SDK's agent loop control patterns

package/docs/api-reference/workflow-ai/index.mdx

@@ -1,21 +1,21 @@
 ---
 title: "@workflow/ai"
-description: Helpers for building AI-powered workflows with the AI SDK.
+description: Deprecated AI integration APIs kept for existing Workflow applications.
 type: overview
-summary: Explore helpers for integrating AI SDK to build durable AI-powered workflows.
+summary: Migrate legacy @workflow/ai APIs to AI SDK's WorkflowAgent and WorkflowChatTransport.
 related:
   - /docs/ai
 ---
 
-Helpers for integrating AI SDK for building AI-powered workflows.
+The `@workflow/ai` package is deprecated in Workflow 5 and remains documented for existing applications. Build new agents with [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) and [`WorkflowChatTransport`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#resumable-streaming-with-workflowchattransport) from `@ai-sdk/workflow`.
 
 ## Classes
 
 <Cards>
     <Card title="DurableAgent" href="/docs/api-reference/workflow-ai/durable-agent">
-      A class for building durable AI agents that maintain state across workflow steps and handle tool execution with automatic retries.
+      Deprecated: use AI SDK's [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent). Reference kept for existing `@workflow/ai/agent` imports.
     </Card>
     <Card title="WorkflowChatTransport" href="/docs/api-reference/workflow-ai/workflow-chat-transport">
-      A drop-in transport for the AI SDK for automatic reconnection in interrupted streams.
+      Deprecated: use AI SDK's [`WorkflowChatTransport`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#resumable-streaming-with-workflowchattransport) from `@ai-sdk/workflow`. Reference kept for existing `@workflow/ai` imports.
     </Card>
 </Cards>