ai 6.0.31 → 6.0.33

package/docs/08-migration-guides/26-migration-guide-5-0.mdx

@@ -0,0 +1,3427 @@
+---
+title: Migrate AI SDK 4.x to 5.0
+description: Learn how to upgrade AI SDK 4.x to 5.0.
+---
+
+# Migrate AI SDK 4.x to 5.0
+
+## Recommended Migration Process
+
+1. Backup your project. If you use a versioning control system, make sure all previous versions are committed.
+1. Upgrade to AI SDK 5.0.
+1. Automatically migrate your code using one of these approaches:
+   - Use the [AI SDK 5 Migration MCP Server](#ai-sdk-5-migration-mcp-server) for AI-assisted migration in Cursor or other MCP-compatible coding agents
+   - Use [codemods](#codemods) to automatically transform your code
+1. Follow the breaking changes guide below.
+1. Verify your project is working as expected.
+1. Commit your changes.
+
+## AI SDK 5 Migration MCP Server
+
+The [AI SDK 5 Migration Model Context Protocol (MCP) Server](https://github.com/vercel-labs/ai-sdk-5-migration-mcp-server) provides an automated way to migrate your project using a coding agent. This server has been designed for Cursor, but should work with any coding agent that supports MCP.
+
+To get started, create or edit `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "ai-sdk-5-migration": {
+      "url": "https://ai-sdk-5-migration-mcp-server.vercel.app/api/mcp"
+    }
+  }
+}
+```
+
+After saving, open the command palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows/Linux) and search for "View: Open MCP Settings". Verify the new server appears and is toggled on.
+
+Then use this prompt:
+
+```
+Please migrate this project to AI SDK 5 using the ai-sdk-5-migration mcp server. Start by creating a checklist.
+```
+
+For more information, see the [AI SDK 5 Migration MCP Server repository](https://github.com/vercel-labs/ai-sdk-5-migration-mcp-server).
+
+## AI SDK 5.0 Package Versions
+
+You need to update the following packages to the following versions in your `package.json` file(s):
+
+- `ai` package: `5.0.0`
+- `@ai-sdk/provider` package: `2.0.0`
+- `@ai-sdk/provider-utils` package: `3.0.0`
+- `@ai-sdk/*` packages: `2.0.0` (other `@ai-sdk` packages)
+
+Additionally, you need to update the following peer dependencies:
+
+- `zod` package: `4.1.8` or later (recommended to avoid TypeScript performance issues)
+
+An example upgrade command would be:
+
+```
+npm install ai @ai-sdk/react @ai-sdk/openai zod@^4.1.8
+```
+
+<Note>
+  If you encounter TypeScript performance issues after upgrading, ensure you're
+  using Zod 4.1.8 or later. If the issue persists, update your `tsconfig.json`
+  to use `moduleResolution: "nodenext"`. See the [TypeScript performance
+  troubleshooting guide](/docs/troubleshooting/typescript-performance-zod) for
+  more details.
+</Note>
+
+## Codemods
+
+The AI SDK provides Codemod transformations to help upgrade your codebase when a
+feature is deprecated, removed, or otherwise changed.
+
+Codemods are transformations that run on your codebase automatically. They
+allow you to easily apply many changes without having to manually go through
+every file.
+
+<Note>
+  Codemods are intended as a tool to help you with the upgrade process. They may
+  not cover all of the changes you need to make. You may need to make additional
+  changes manually.
+</Note>
+
+You can run all codemods provided as part of the 5.0 upgrade process by running
+the following command from the root of your project:
+
+```sh
+npx @ai-sdk/codemod upgrade
+```
+
+To run only the v5 codemods (v4 → v5 migration):
+
+```sh
+npx @ai-sdk/codemod v5
+```
+
+Individual codemods can be run by specifying the name of the codemod:
+
+```sh
+npx @ai-sdk/codemod <codemod-name> <path>
+```
+
+For example, to run a specific v5 codemod:
+
+```sh
+npx @ai-sdk/codemod v5/rename-format-stream-part src/
+```
+
+See also the [table of codemods](#codemod-table). In addition, the latest set of
+codemods can be found in the
+[`@ai-sdk/codemod`](https://github.com/vercel/ai/tree/main/packages/codemod/src/codemods)
+repository.
+
+## AI SDK Core Changes
+
+### generateText and streamText Changes
+
+#### Maximum Output Tokens
+
+The `maxTokens` parameter has been renamed to `maxOutputTokens` for clarity.
+
+```tsx filename="AI SDK 4.0"
+const result = await generateText({
+  model: __MODEL__,
+  maxTokens: 1024,
+  prompt: 'Hello, world!',
+});
+```
+
+```tsx filename="AI SDK 5.0"
+const result = await generateText({
+  model: __MODEL__,
+  maxOutputTokens: 1024,
+  prompt: 'Hello, world!',
+});
+```
+
+### Message and Type System Changes
+
+#### Core Type Renames
+
+##### `CoreMessage` → `ModelMessage`
+
+```tsx filename="AI SDK 4.0"
+import { CoreMessage } from 'ai';
+```
+
+```tsx filename="AI SDK 5.0"
+import { ModelMessage } from 'ai';
+```
+
+##### `Message` → `UIMessage`
+
+```tsx filename="AI SDK 4.0"
+import { Message, CreateMessage } from 'ai';
+```
+
+```tsx filename="AI SDK 5.0"
+import { UIMessage, CreateUIMessage } from 'ai';
+```
+
+##### `convertToCoreMessages` → `convertToModelMessages`
+
+```tsx filename="AI SDK 4.0"
+import { convertToCoreMessages, streamText } from 'ai';
+
+const result = await streamText({
+  model: __MODEL__,
+  messages: convertToCoreMessages(messages),
+});
+```
+
+```tsx filename="AI SDK 5.0"
+import { convertToModelMessages, streamText } from 'ai';
+
+const result = await streamText({
+  model: __MODEL__,
+  messages: convertToModelMessages(messages),
+});
+```
+
+<Note>
+  For more information about model messages, see the [Model Message
+  reference](/docs/reference/ai-sdk-core/model-message).
+</Note>
+
+### UIMessage Changes
+
+#### Content → Parts Array
+
+For `UIMessage`s (previously called `Message`), the `.content` property has been replaced with a `parts` array structure.
+
+```tsx filename="AI SDK 4.0"
+import { type Message } from 'ai'; // v4 Message type
+
+// Messages (useChat) - had content property
+const message: Message = {
+  id: '1',
+  role: 'user',
+  content: 'Bonjour!',
+};
+```
+
+```tsx filename="AI SDK 5.0"
+import { type UIMessage, type ModelMessage } from 'ai';
+
+// UIMessages (useChat) - now use parts array
+const uiMessage: UIMessage = {
+  id: '1',
+  role: 'user',
+  parts: [{ type: 'text', text: 'Bonjour!' }],
+};
+```
+
+#### Data Role Removed
+
+The `data` role has been removed from UI messages.
+
+```tsx filename="AI SDK 4.0"
+const message = {
+  role: 'data',
+  content: 'Some content',
+  data: { customField: 'value' },
+};
+```
+
+```tsx filename="AI SDK 5.0"
+// V5: Use UI message streams with custom data parts
+const stream = createUIMessageStream({
+  execute({ writer }) {
+    // Write custom data instead of message annotations
+    writer.write({
+      type: 'data-custom',
+      id: 'custom-1',
+      data: { customField: 'value' },
+    });
+  },
+});
+```
+
+#### UIMessage Reasoning Structure
+
+The reasoning property on UI messages has been moved to parts.
+
+```tsx filename="AI SDK 4.0"
+const message: Message = {
+  role: 'assistant',
+  content: 'Hello',
+  reasoning: 'I will greet the user',
+};
+```
+
+```tsx filename="AI SDK 5.0"
+const message: UIMessage = {
+  role: 'assistant',
+  parts: [
+    {
+      type: 'reasoning',
+      text: 'I will greet the user',
+    },
+    {
+      type: 'text',
+      text: 'Hello',
+    },
+  ],
+};
+```
+
+#### Reasoning Part Property Rename
+
+The `reasoning` property on reasoning UI parts has been renamed to `text`.
+
+```tsx filename="AI SDK 4.0"
+{
+  message.parts.map((part, index) => {
+    if (part.type === 'reasoning') {
+      return (
+        <div key={index} className="reasoning-display">
+          {part.reasoning}
+        </div>
+      );
+    }
+  });
+}
+```
+
+```tsx filename="AI SDK 5.0"
+{
+  message.parts.map((part, index) => {
+    if (part.type === 'reasoning') {
+      return (
+        <div key={index} className="reasoning-display">
+          {part.text}
+        </div>
+      );
+    }
+  });
+}
+```
+
+### File Part Changes
+
+File parts now use `.url` instead of `.data` and `.mimeType`.
+
+```tsx filename="AI SDK 4.0"
+{
+  messages.map(message => (
+    <div key={message.id}>
+      {message.parts.map((part, index) => {
+        if (part.type === 'text') {
+          return <div key={index}>{part.text}</div>;
+        } else if (part.type === 'file' && part.mimeType.startsWith('image/')) {
+          return (
+            <img
+              key={index}
+              src={`data:${part.mimeType};base64,${part.data}`}
+            />
+          );
+        }
+      })}
+    </div>
+  ));
+}
+```
+
+```tsx filename="AI SDK 5.0"
+{
+  messages.map(message => (
+    <div key={message.id}>
+      {message.parts.map((part, index) => {
+        if (part.type === 'text') {
+          return <div key={index}>{part.text}</div>;
+        } else if (
+          part.type === 'file' &&
+          part.mediaType.startsWith('image/')
+        ) {
+          return <img key={index} src={part.url} />;
+        }
+      })}
+    </div>
+  ));
+}
+```
+
+### Stream Data Removal
+
+The `StreamData` class has been completely removed and replaced with UI message streams for custom data.
+
+```tsx filename="AI SDK 4.0"
+import { StreamData } from 'ai';
+
+const streamData = new StreamData();
+streamData.append('custom-data');
+streamData.close();
+```
+
+```tsx filename="AI SDK 5.0"
+import { createUIMessageStream, createUIMessageStreamResponse } from 'ai';
+
+const stream = createUIMessageStream({
+  execute({ writer }) {
+    // Write custom data parts
+    writer.write({
+      type: 'data-custom',
+      id: 'custom-1',
+      data: 'custom-data',
+    });
+
+    // Can merge with LLM streams
+    const result = streamText({
+      model: __MODEL__,
+      messages,
+    });
+
+    writer.merge(result.toUIMessageStream());
+  },
+});
+
+return createUIMessageStreamResponse({ stream });
+```
+
+### Custom Data Streaming: writeMessageAnnotation/writeData Removed
+
+The `writeMessageAnnotation` and `writeData` methods from `DataStreamWriter` have been removed. Instead, use custom data parts with the new `UIMessage` stream architecture.
+
+```tsx filename="AI SDK 4.0"
+import { createDataStreamResponse, streamText } from 'ai';
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  return createDataStreamResponse({
+    execute: dataStream => {
+      // Write general data
+      dataStream.writeData('call started');
+
+      const result = streamText({
+        model: __MODEL__,
+        messages,
+        onChunk() {
+          // Write message annotations
+          dataStream.writeMessageAnnotation({
+            status: 'streaming',
+            timestamp: Date.now(),
+          });
+        },
+        onFinish() {
+          // Write final annotations
+          dataStream.writeMessageAnnotation({
+            id: generateId(),
+            completed: true,
+          });
+
+          dataStream.writeData('call completed');
+        },
+      });
+
+      result.mergeIntoDataStream(dataStream);
+    },
+  });
+}
+```
+
+```tsx filename="AI SDK 5.0"
+import {
+  createUIMessageStream,
+  createUIMessageStreamResponse,
+  streamText,
+  generateId,
+} from 'ai';
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const stream = createUIMessageStream({
+    execute: ({ writer }) => {
+      const statusId = generateId();
+
+      // Write general data (transient - not added to message history)
+      writer.write({
+        type: 'data-status',
+        id: statusId,
+        data: { status: 'call started' },
+      });
+
+      const result = streamText({
+        model: __MODEL__,
+        messages,
+        onChunk() {
+          // Write data parts that update during streaming
+          writer.write({
+            type: 'data-status',
+            id: statusId,
+            data: {
+              status: 'streaming',
+              timestamp: Date.now(),
+            },
+          });
+        },
+        onFinish() {
+          // Write final data parts
+          writer.write({
+            type: 'data-status',
+            id: statusId,
+            data: {
+              status: 'completed',
+            },
+          });
+        },
+      });
+
+      writer.merge(result.toUIMessageStream());
+    },
+  });
+
+  return createUIMessageStreamResponse({ stream });
+}
+```
+
+<Note>
+  For more detailed information about streaming custom data in v5, see the
+  [Streaming Data guide](/docs/ai-sdk-ui/streaming-data).
+</Note>
+
+##### Provider Metadata → Provider Options
+
+The `providerMetadata` input parameter has been renamed to `providerOptions`. Note that the returned metadata in results is still called `providerMetadata`.
+
+```tsx filename="AI SDK 4.0"
+const result = await generateText({
+  model: 'openai/gpt-5',
+  prompt: 'Hello',
+  providerMetadata: {
+    openai: { store: false },
+  },
+});
+```
+
+```tsx filename="AI SDK 5.0"
+const result = await generateText({
+  model: 'openai/gpt-5',
+  prompt: 'Hello',
+  providerOptions: {
+    // Input parameter renamed
+    openai: { store: false },
+  },
+});
+
+// Returned metadata still uses providerMetadata:
+console.log(result.providerMetadata?.openai);
+```
+
+#### Tool Definition Changes (parameters → inputSchema)
+
+Tool definitions have been updated to use `inputSchema` instead of `parameters` and error classes have been renamed.
+
+```tsx filename="AI SDK 4.0"
+import { tool } from 'ai';
+
+const weatherTool = tool({
+  description: 'Get the weather for a city',
+  parameters: z.object({
+    city: z.string(),
+  }),
+  execute: async ({ city }) => {
+    return `Weather in ${city}`;
+  },
+});
+```
+
+```tsx filename="AI SDK 5.0"
+import { tool } from 'ai';
+
+const weatherTool = tool({
+  description: 'Get the weather for a city',
+  inputSchema: z.object({
+    city: z.string(),
+  }),
+  execute: async ({ city }) => {
+    return `Weather in ${city}`;
+  },
+});
+```
+
+#### Tool Result Content: experimental_toToolResultContent → toModelOutput
+
+The `experimental_toToolResultContent` option has been renamed to `toModelOutput` and is no longer experimental.
+
+```tsx filename="AI SDK 4.0"
+const screenshotTool = tool({
+  description: 'Take a screenshot',
+  parameters: z.object({}),
+  execute: async () => {
+    const imageData = await takeScreenshot();
+    return imageData; // base64 string
+  },
+  experimental_toToolResultContent: result => [{ type: 'image', data: result }],
+});
+```
+
+```tsx filename="AI SDK 5.0"
+const screenshotTool = tool({
+  description: 'Take a screenshot',
+  inputSchema: z.object({}),
+  execute: async () => {
+    const imageData = await takeScreenshot();
+    return imageData;
+  },
+  toModelOutput: result => ({
+    type: 'content',
+    value: [{ type: 'media', mediaType: 'image/png', data: result }],
+  }),
+});
+```
+
+### Tool Property Changes (args/result → input/output)
+
+Tool call and result properties have been renamed for better consistency with schemas.
+
+```tsx filename="AI SDK 4.0"
+// Tool calls used "args" and "result"
+for await (const part of result.fullStream) {
+  switch (part.type) {
+    case 'tool-call':
+      console.log('Tool args:', part.args);
+      break;
+    case 'tool-result':
+      console.log('Tool result:', part.result);
+      break;
+  }
+}
+```
+
+```tsx filename="AI SDK 5.0"
+// Tool calls now use "input" and "output"
+for await (const part of result.fullStream) {
+  switch (part.type) {
+    case 'tool-call':
+      console.log('Tool input:', part.input);
+      break;
+    case 'tool-result':
+      console.log('Tool output:', part.output);
+      break;
+  }
+}
+```
+
+### Tool Execution Error Handling
+
+The `ToolExecutionError` class has been removed. Tool execution errors now appear as `tool-error` content parts in the result steps, enabling automated LLM roundtrips in multi-step scenarios.
+
+```tsx filename="AI SDK 4.0"
+import { ToolExecutionError } from 'ai';
+
+try {
+  const result = await generateText({
+    // ...
+  });
+} catch (error) {
+  if (error instanceof ToolExecutionError) {
+    console.log('Tool execution failed:', error.message);
+    console.log('Tool name:', error.toolName);
+    console.log('Tool input:', error.toolInput);
+  }
+}
+```
+
+```tsx filename="AI SDK 5.0"
+// Tool execution errors now appear in result steps
+const { steps } = await generateText({
+  // ...
+});
+
+// check for tool errors in the steps
+const toolErrors = steps.flatMap(step =>
+  step.content.filter(part => part.type === 'tool-error'),
+);
+
+toolErrors.forEach(toolError => {
+  console.log('Tool error:', toolError.error);
+  console.log('Tool name:', toolError.toolName);
+  console.log('Tool input:', toolError.input);
+});
+```
+
+For streaming scenarios, tool execution errors appear as `tool-error` parts in the stream, while other errors appear as `error` parts.
+
+### Tool Call Streaming Now Default (toolCallStreaming Removed)
+
+The `toolCallStreaming` option has been removed in AI SDK 5.0. Tool call streaming is now always enabled by default.
+
+```tsx filename="AI SDK 4.0"
+const result = streamText({
+  model: __MODEL__,
+  messages,
+  toolCallStreaming: true, // Optional parameter to enable streaming
+  tools: {
+    weatherTool,
+    searchTool,
+  },
+});
+```
+
+```tsx filename="AI SDK 5.0"
+const result = streamText({
+  model: __MODEL__,
+  messages: convertToModelMessages(messages),
+  // toolCallStreaming removed - streaming is always enabled
+  tools: {
+    weatherTool,
+    searchTool,
+  },
+});
+```
+
+### Tool Part Type Changes (UIMessage)
+
+In v5, UI tool parts use typed naming: `tool-${toolName}` instead of generic types.
+
+```tsx filename="AI SDK 4.0"
+// Generic tool-invocation type
+{
+  message.parts.map(part => {
+    if (part.type === 'tool-invocation') {
+      return <div>{part.toolInvocation.toolName}</div>;
+    }
+  });
+}
+```
+
+```tsx filename="AI SDK 5.0"
+// Type-safe tool parts with specific names
+{
+  message.parts.map(part => {
+    switch (part.type) {
+      case 'tool-getWeatherInformation':
+        return <div>Getting weather...</div>;
+      case 'tool-askForConfirmation':
+        return <div>Asking for confirmation...</div>;
+    }
+  });
+}
+```
+
+### Dynamic Tools Support
+
+AI SDK 5.0 introduces dynamic tools for handling tools with unknown types at development time, such as MCP tools without schemas or user-defined functions at runtime.
+
+#### New dynamicTool Helper
+
+The new `dynamicTool` helper function allows you to define tools where the input and output types are not known at compile time.
+
+```tsx filename="AI SDK 5.0"
+import { dynamicTool } from 'ai';
+import { z } from 'zod';
+
+// Define a dynamic tool
+const runtimeTool = dynamicTool({
+  description: 'A tool defined at runtime',
+  inputSchema: z.object({}),
+  execute: async input => {
+    // Input and output are typed as 'unknown'
+    return { result: `Processed: ${input.query}` };
+  },
+});
+```
+
+#### MCP Tools Without Schemas
+
+MCP tools that don't provide schemas are now automatically treated as dynamic tools:
+
+```tsx filename="AI SDK 5.0"
+import { MCPClient } from 'ai';
+
+const client = new MCPClient({
+  /* ... */
+});
+const tools = await client.getTools();
+
+// Tools without schemas are now 'dynamic' type
+// and won't break type inference when mixed with static tools
+```
+
+#### Type-Safe Handling with Mixed Tools
+
+When using both static and dynamic tools together, use the `dynamic` flag for type narrowing:
+
+```tsx filename="AI SDK 5.0"
+const result = await generateText({
+  model: __MODEL__,
+  tools: {
+    // Static tool with known types
+    weather: weatherTool,
+    // Dynamic tool with unknown types
+    customDynamicTool: dynamicTool({
+      /* ... */
+    }),
+  },
+  onStepFinish: step => {
+    // Handle tool calls with type safety
+    for (const toolCall of step.toolCalls) {
+      if (toolCall.dynamic) {
+        // Dynamic tool: input/output are 'unknown'
+        console.log('Dynamic tool called:', toolCall.toolName);
+        continue;
+      }
+
+      // Static tools have full type inference
+      switch (toolCall.toolName) {
+        case 'weather':
+          // TypeScript knows the exact types
+          console.log(toolCall.input.location); // string
+          break;
+      }
+    }
+  },
+});
+```
+
+#### New dynamic-tool UI Part
+
+UI messages now include a `dynamic-tool` part type for rendering dynamic tool invocations:
+
+```tsx filename="AI SDK 5.0"
+{
+  message.parts.map((part, index) => {
+    switch (part.type) {
+      // Static tools use specific types
+      case 'tool-weather':
+        return <div>Weather: {part.input.city}</div>;
+
+      // Dynamic tools use the generic dynamic-tool type
+      case 'dynamic-tool':
+        return (
+          <div>
+            Dynamic tool: {part.toolName}
+            <pre>{JSON.stringify(part.input, null, 2)}</pre>
+          </div>
+        );
+    }
+  });
+}
+```
+
+#### Breaking Change: Type Narrowing Required for Tool Calls and Results
+
+When iterating over `toolCalls` and `toolResults`, you now need to check the `dynamic` flag first for proper type narrowing:
+
+```tsx filename="AI SDK 4.0"
+// Direct type checking worked without dynamic flag
+onStepFinish: step => {
+  for (const toolCall of step.toolCalls) {
+    switch (toolCall.toolName) {
+      case 'weather':
+        console.log(toolCall.input.location); // typed as string
+        break;
+      case 'search':
+        console.log(toolCall.input.query); // typed as string
+        break;
+    }
+  }
+};
+```
+
+```tsx filename="AI SDK 5.0"
+// Must check dynamic flag first for type narrowing
+onStepFinish: step => {
+  for (const toolCall of step.toolCalls) {
+    // Check if it's a dynamic tool first
+    if (toolCall.dynamic) {
+      console.log('Dynamic tool:', toolCall.toolName);
+      console.log('Input:', toolCall.input); // typed as unknown
+      continue;
+    }
+
+    // Now TypeScript knows it's a static tool
+    switch (toolCall.toolName) {
+      case 'weather':
+        console.log(toolCall.input.location); // typed as string
+        break;
+      case 'search':
+        console.log(toolCall.input.query); // typed as string
+        break;
+    }
+  }
+};
+```
+
+### Tool UI Part State Changes
+
+Tool UI parts now use more granular states that better represent the streaming lifecycle and error handling.
+
+```tsx filename="AI SDK 4.0"
+// Old states
+{
+  message.parts.map(part => {
+    if (part.type === 'tool-invocation') {
+      switch (part.toolInvocation.state) {
+        case 'partial-call':
+          return <div>Loading...</div>;
+        case 'call':
+          return (
+            <div>
+              Tool called with {JSON.stringify(part.toolInvocation.args)}
+            </div>
+          );
+        case 'result':
+          return <div>Result: {part.toolInvocation.result}</div>;
+      }
+    }
+  });
+}
+```
+
+```tsx filename="AI SDK 5.0"
+// New granular states
+{
+  message.parts.map(part => {
+    switch (part.type) {
+      case 'tool-getWeatherInformation':
+        switch (part.state) {
+          case 'input-streaming':
+            return <pre>{JSON.stringify(part.input, null, 2)}</pre>;
+          case 'input-available':
+            return <div>Getting weather for {part.input.city}...</div>;
+          case 'output-available':
+            return <div>Weather: {part.output}</div>;
+          case 'output-error':
+            return <div>Error: {part.errorText}</div>;
+        }
+    }
+  });
+}
+```
+
+**State Changes:**
+
+- `partial-call` → `input-streaming` (tool input being streamed)
+- `call` → `input-available` (tool input complete, ready to execute)
+- `result` → `output-available` (tool execution successful)
+- New: `output-error` (tool execution failed)
+
+#### Rendering Tool Invocations (Catch-All Pattern)
+
+In v4, you typically rendered tool invocations using a catch-all `tool-invocation` type. In v5, the **recommended approach is to handle each tool specifically using its typed part name (e.g., `tool-getWeather`)**. However, if you need a catch-all pattern for rendering all tool invocations the same way, you can use the `isToolUIPart` and `getToolName` helper functions as a fallback.
+
+```tsx filename="AI SDK 4.0"
+{
+  message.parts.map((part, index) => {
+    switch (part.type) {
+      case 'text':
+        return <div key={index}>{part.text}</div>;
+      case 'tool-invocation':
+        const { toolInvocation } = part;
+        return (
+          <details key={`tool-${toolInvocation.toolCallId}`}>
+            <summary>
+              <span>{toolInvocation.toolName}</span>
+              {toolInvocation.state === 'result' ? (
+                <span>Click to expand</span>
+              ) : (
+                <span>calling...</span>
+              )}
+            </summary>
+            {toolInvocation.state === 'result' ? (
+              <div>
+                <pre>{JSON.stringify(toolInvocation.result, null, 2)}</pre>
+              </div>
+            ) : null}
+          </details>
+        );
+    }
+  });
+}
+```
+
+```tsx filename="AI SDK 5.0"
+import { isToolUIPart, getToolName } from 'ai';
+
+{
+  message.parts.map((part, index) => {
+    switch (part.type) {
+      case 'text':
+        return <div key={index}>{part.text}</div>;
+      default:
+        if (isToolUIPart(part)) {
+          const toolInvocation = part;
+          return (
+            <details key={`tool-${toolInvocation.toolCallId}`}>
+              <summary>
+                <span>{getToolName(toolInvocation)}</span>
+                {toolInvocation.state === 'output-available' ? (
+                  <span>Click to expand</span>
+                ) : (
+                  <span>calling...</span>
+                )}
+              </summary>
+              {toolInvocation.state === 'output-available' ? (
+                <div>
+                  <pre>{JSON.stringify(toolInvocation.output, null, 2)}</pre>
+                </div>
+              ) : null}
+            </details>
+          );
+        }
+    }
+  });
+}
+```
+
+#### Media Type Standardization
+
+`mimeType` has been renamed to `mediaType` for consistency. Both image and file types are supported in model messages.
+
+```tsx filename="AI SDK 4.0"
+const result = await generateText({
+  model: someModel,
+  messages: [
+    {
+      role: 'user',
+      content: [
+        { type: 'text', text: 'What do you see?' },
+        {
+          type: 'image',
+          image: new Uint8Array([0, 1, 2, 3]),
+          mimeType: 'image/png',
+        },
+        {
+          type: 'file',
+          data: contents,
+          mimeType: 'application/pdf',
+        },
+      ],
+    },
+  ],
+});
+```
+
+```tsx filename="AI SDK 5.0"
+const result = await generateText({
+  model: someModel,
+  messages: [
+    {
+      role: 'user',
+      content: [
+        { type: 'text', text: 'What do you see?' },
+        {
+          type: 'image',
+          image: new Uint8Array([0, 1, 2, 3]),
+          mediaType: 'image/png',
+        },
+        {
+          type: 'file',
+          data: contents,
+          mediaType: 'application/pdf',
+        },
+      ],
+    },
+  ],
+});
+```
+
+### Reasoning Support
+
+#### Reasoning Text Property Rename
+
+The `.reasoning` property has been renamed to `.reasoningText` for multi-step generations.
+
+```tsx filename="AI SDK 4.0"
+for (const step of steps) {
+  console.log(step.reasoning);
+}
+```
+
+```tsx filename="AI SDK 5.0"
+for (const step of steps) {
+  console.log(step.reasoningText);
+}
+```
+
+#### Generate Text Reasoning Property Changes
+
+In `generateText()` and `streamText()` results, reasoning properties have been renamed.
+
+```tsx filename="AI SDK 4.0"
+const result = await generateText({
+  model: anthropic('claude-sonnet-4-20250514'),
+  prompt: 'Explain your reasoning',
+});
+
+console.log(result.reasoning); // String reasoning text
+console.log(result.reasoningDetails); // Array of reasoning details
+```
+
+```tsx filename="AI SDK 5.0"
+const result = await generateText({
+  model: anthropic('claude-sonnet-4-20250514'),
+  prompt: 'Explain your reasoning',
+});
+
+console.log(result.reasoningText); // String reasoning text
+console.log(result.reasoning); // Array of reasoning details
+```
+
+### Continuation Steps Removal
+
+The `experimental_continueSteps` option has been removed from `generateText()`.
+
+```tsx filename="AI SDK 4.0"
+const result = await generateText({
+  experimental_continueSteps: true,
+  // ...
+});
+```
+
+```tsx filename="AI SDK 5.0"
+const result = await generateText({
+  // experimental_continueSteps has been removed
+  // Use newer models with higher output token limits instead
+  // ...
+});
+```
+
+### Image Generation Changes
+
+Image model settings have been moved to `providerOptions`.
+
+```tsx filename="AI SDK 4.0"
+await generateImage({
+  model: luma.image('photon-flash-1', {
+    maxImagesPerCall: 5,
+    pollIntervalMillis: 500,
+  }),
+  prompt,
+  n: 10,
+});
+```
+
+```tsx filename="AI SDK 5.0"
+await generateImage({
+  model: luma.image('photon-flash-1'),
+  prompt,
+  n: 10,
+  maxImagesPerCall: 5,
+  providerOptions: {
+    luma: { pollIntervalMillis: 500 },
+  },
+});
+```
+
+### Step Result Changes
+
+#### Step Type Removal
+
+The `stepType` property has been removed from step results.
+
+```tsx filename="AI SDK 4.0"
+steps.forEach(step => {
+  switch (step.stepType) {
+    case 'initial':
+      console.log('Initial step');
+      break;
+    case 'tool-result':
+      console.log('Tool result step');
+      break;
+    case 'done':
+      console.log('Final step');
+      break;
+  }
+});
+```
+
+```tsx filename="AI SDK 5.0"
+steps.forEach((step, index) => {
+  if (index === 0) {
+    console.log('Initial step');
+  } else if (step.toolResults.length > 0) {
+    console.log('Tool result step');
+  } else {
+    console.log('Final step');
+  }
+});
+```
+
+### Step Control: maxSteps → stopWhen
+
+For core functions like `generateText` and `streamText`, the `maxSteps` parameter has been replaced with `stopWhen`, which provides more flexible control over multi-step execution. The `stopWhen` parameter defines conditions for stopping the generation **when the last step contains tool results**. When multiple conditions are provided as an array, the generation stops if any condition is met.
+
+```tsx filename="AI SDK 4.0"
+// V4: Simple numeric limit
+const result = await generateText({
+  model: __MODEL__,
+  messages,
+  maxSteps: 5, // Stop after a maximum of 5 steps
+});
+
+// useChat with maxSteps
+const { messages } = useChat({
+  maxSteps: 3, // Stop after a maximum of 3 steps
+});
+```
+
+```tsx filename="AI SDK 5.0"
+import { stepCountIs, hasToolCall } from 'ai';
+
+// V5: Server-side - flexible stopping conditions with stopWhen
+const result = await generateText({
+  model: __MODEL__,
+  messages,
+  // Only triggers when last step has tool results
+  stopWhen: stepCountIs(5), // Stop at step 5 if tools were called
+});
+
+// Server-side - stop when specific tool is called
+const result = await generateText({
+  model: __MODEL__,
+  messages,
+  stopWhen: hasToolCall('finalizeTask'), // Stop when finalizeTask tool is called
+});
+```
+
+**Common stopping patterns:**
+
+```tsx filename="AI SDK 5.0"
+// Stop after N steps (equivalent to old maxSteps)
+// Note: Only applies when the last step has tool results
+stopWhen: stepCountIs(5);
+
+// Stop when specific tool is called
+stopWhen: hasToolCall('finalizeTask');
+
+// Multiple conditions (stops if ANY condition is met)
+stopWhen: [
+  stepCountIs(10), // Maximum 10 steps
+  hasToolCall('submitOrder'), // Or when order is submitted
+];
+
+// Custom condition based on step content
+stopWhen: ({ steps }) => {
+  const lastStep = steps[steps.length - 1];
+  // Custom logic - only triggers if last step has tool results
+  return lastStep?.text?.includes('COMPLETE');
+};
+```
+
+**Important:** The `stopWhen` conditions are only evaluated when the last step contains tool results.
+
+#### Usage vs Total Usage
+
+Usage properties now distinguish between single step and total usage.
+
+```tsx filename="AI SDK 4.0"
+// usage contained total token usage across all steps
+console.log(result.usage);
+```
+
+```tsx filename="AI SDK 5.0"
+// usage contains token usage from the final step only
+console.log(result.usage);
+// totalUsage contains total token usage across all steps
+console.log(result.totalUsage);
+```
+
+## AI SDK UI Changes
+
+### Package Structure Changes
+
+### `@ai-sdk/rsc` Package Extraction
+
+The `ai/rsc` export has been extracted to a separate package `@ai-sdk/rsc`.
+
+```tsx filename="AI SDK 4.0"
+import { createStreamableValue } from 'ai/rsc';
+```
+
+```tsx filename="AI SDK 5.0"
+import { createStreamableValue } from '@ai-sdk/rsc';
+```
+
+<Note>Don't forget to install the new package: `npm install @ai-sdk/rsc`</Note>
+
+### React UI Hooks Moved to `@ai-sdk/react`
+
+The deprecated `ai/react` export has been removed in favor of `@ai-sdk/react`.
+
+```tsx filename="AI SDK 4.0"
+import { useChat } from 'ai/react';
+```
+
+```tsx filename="AI SDK 5.0"
+import { useChat } from '@ai-sdk/react';
+```
+
+<Note>
+  Don't forget to install the new package: `npm install @ai-sdk/react`
+</Note>
+
+### useChat Changes
+
+The `useChat` hook has undergone significant changes in v5, with new transport architecture, removal of managed input state, and more.
+
+#### maxSteps Removal
+
+The `maxSteps` parameter has been removed from `useChat`. You should now use server-side `stopWhen` conditions for multi-step tool execution control, and manually submit tool results and trigger new messages for client-side tool calls.
+
+```tsx filename="AI SDK 4.0"
+const { messages, sendMessage } = useChat({
+  maxSteps: 5, // Automatic tool result submission
+});
+```
+
+```tsx filename="AI SDK 5.0"
+// Server-side: Use stopWhen for multi-step control
+import { streamText, convertToModelMessages, stepCountIs } from 'ai';
+__PROVIDER_IMPORT__;
+
+const result = await streamText({
+  model: __MODEL__,
+  messages: convertToModelMessages(messages),
+  stopWhen: stepCountIs(5), // Stop after 5 steps with tool calls
+});
+
+// Client-side: Configure automatic submission
+import { useChat } from '@ai-sdk/react';
+import {
+  DefaultChatTransport,
+  lastAssistantMessageIsCompleteWithToolCalls,
+} from 'ai';
+
+const { messages, sendMessage, addToolOutput } = useChat({
+  // Automatically submit when all tool results are available
+  sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
+
+  async onToolCall({ toolCall }) {
+    const result = await executeToolCall(toolCall);
+
+    // Important: Don't await addToolOutput inside onToolCall to avoid deadlocks
+    addToolOutput({
+      tool: toolCall.toolName,
+      toolCallId: toolCall.toolCallId,
+      output: result,
+    });
+  },
+});
+```
+
+<Note>
+  Important: When using `sendAutomaticallyWhen`, don't use `await` with
+  `addToolOutput` inside `onToolCall` as it can cause deadlocks. The `await` is
+  useful when you're not using automatic submission and need to ensure the
+  messages are updated before manually calling `sendMessage()`.
+</Note>
+
+This change provides more flexibility for handling tool calls and aligns client behavior with server-side multi-step execution patterns.
+
+For more details on the new tool submission approach, see the [Tool Result Submission Changes](#tool-result-submission-changes) section below.
+
+#### Initial Messages Renamed
+
+The `initialMessages` option has been renamed to `messages`.
+
+```tsx filename="AI SDK 4.0"
+import { useChat, type Message } from '@ai-sdk/react';
+
+function ChatComponent({ initialMessages }: { initialMessages: Message[] }) {
+  const { messages } = useChat({
+    initialMessages: initialMessages,
+    // ...
+  });
+
+  // your component
+}
+```
+
+```tsx filename="AI SDK 5.0"
+import { useChat, type UIMessage } from '@ai-sdk/react';
+
+function ChatComponent({ initialMessages }: { initialMessages: UIMessage[] }) {
+  const { messages } = useChat({
+    messages: initialMessages,
+    // ...
+  });
+
+  // your component
+}
+```
+
+#### Sharing Chat Instances
+
+In v4, you could share chat state between components by using the same `id` parameter in multiple `useChat` hooks.
+
+```tsx filename="AI SDK 4.0"
+// Component A
+const { messages } = useChat({
+  id: 'shared-chat',
+  api: '/api/chat',
+});
+
+// Component B - would share the same chat state
+const { messages } = useChat({
+  id: 'shared-chat',
+  api: '/api/chat',
+});
+```
+
+In v5, you need to explicitly share chat instances by passing a shared `Chat` instance.
+
+```tsx filename="AI SDK 5.0"
+// e.g. Store Chat instance in React Context and create a custom hook
+
+// Component A
+const { chat } = useSharedChat(); // Custom hook that accesses shared Chat from context
+
+const { messages, sendMessage } = useChat({
+  chat, // Pass the shared chat instance
+});
+
+// Component B - shares the same chat instance
+const { chat } = useSharedChat(); // Same hook to access shared Chat from context
+
+const { messages } = useChat({
+  chat, // Same shared chat instance
+});
+```
+
+For a complete example of sharing chat state across components, see the [Share Chat State Across Components](/docs/cookbook/use-shared-chat-context) recipe.
+
+#### Chat Transport Architecture
+
+Configuration is now handled through transport objects instead of direct API options.
+
+```tsx filename="AI SDK 4.0"
+import { useChat } from '@ai-sdk/react';
+
+const { messages } = useChat({
+  api: '/api/chat',
+  credentials: 'include',
+  headers: { 'Custom-Header': 'value' },
+});
+```
+
+```tsx filename="AI SDK 5.0"
+import { useChat } from '@ai-sdk/react';
+import { DefaultChatTransport } from 'ai';
+
+const { messages } = useChat({
+  transport: new DefaultChatTransport({
+    api: '/api/chat',
+    credentials: 'include',
+    headers: { 'Custom-Header': 'value' },
+  }),
+});
+```
+
+#### Removed Managed Input State
+
+The `useChat` hook no longer manages input state internally. You must now manage input state manually.
+
+```tsx filename="AI SDK 4.0"
+import { useChat } from '@ai-sdk/react';
+
+export default function Page() {
+  const { messages, input, handleInputChange, handleSubmit } = useChat({
+    api: '/api/chat',
+  });
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input value={input} onChange={handleInputChange} />
+      <button type="submit">Send</button>
+    </form>
+  );
+}
+```
+
+```tsx filename="AI SDK 5.0"
+import { useChat } from '@ai-sdk/react';
+import { DefaultChatTransport } from 'ai';
+import { useState } from 'react';
+
+export default function Page() {
+  const [input, setInput] = useState('');
+  const { messages, sendMessage } = useChat({
+    transport: new DefaultChatTransport({ api: '/api/chat' }),
+  });
+
+  const handleSubmit = e => {
+    e.preventDefault();
+    sendMessage({ text: input });
+    setInput('');
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input value={input} onChange={e => setInput(e.target.value)} />
+      <button type="submit">Send</button>
+    </form>
+  );
+}
+```
+
+#### Message Sending: `append` → `sendMessage`
+
+The `append` function has been replaced with `sendMessage` and requires structured message format.
+
+```tsx filename="AI SDK 4.0"
+const { append } = useChat();
+
+// Simple text message
+append({ role: 'user', content: 'Hello' });
+
+// With custom body
+append(
+  {
+    role: 'user',
+    content: 'Hello',
+  },
+  { body: { imageUrl: 'https://...' } },
+);
+```
+
+```tsx filename="AI SDK 5.0"
+const { sendMessage } = useChat();
+
+// Simple text message (most common usage)
+sendMessage({ text: 'Hello' });
+
+// Or with explicit parts array
+sendMessage({
+  parts: [{ type: 'text', text: 'Hello' }],
+});
+
+// With custom body (via request options)
+sendMessage(
+  { role: 'user', parts: [{ type: 'text', text: 'Hello' }] },
+  { body: { imageUrl: 'https://...' } },
+);
+```
+
+#### Message Regeneration: `reload` → `regenerate`
+
+The `reload` function has been renamed to `regenerate` with enhanced functionality.
+
+```tsx filename="AI SDK 4.0"
+const { reload } = useChat();
+
+// Regenerate last message
+reload();
+```
+
+```tsx filename="AI SDK 5.0"
+const { regenerate } = useChat();
+
+// Regenerate last message
+regenerate();
+
+// Regenerate specific message
+regenerate({ messageId: 'message-123' });
+```
+
+#### onResponse Removal
+
+The `onResponse` callback has been removed from `useChat` and `useCompletion`.
+
+```tsx filename="AI SDK 4.0"
+const { messages } = useChat({
+  onResponse(response) {
+    // handle response
+  },
+});
+```
+
+```tsx filename="AI SDK 5.0"
+const { messages } = useChat({
+  // onResponse is no longer available
+});
+```
+
+#### Send Extra Message Fields Default
+
+The `sendExtraMessageFields` option has been removed and is now the default behavior.
+
+```tsx filename="AI SDK 4.0"
+const { messages } = useChat({
+  sendExtraMessageFields: true,
+});
+```
+
+```tsx filename="AI SDK 5.0"
+const { messages } = useChat({
+  // sendExtraMessageFields is now the default
+});
+```
+
+#### Keep Last Message on Error Removal
+
+The `keepLastMessageOnError` option has been removed as it's no longer needed.
+
+```tsx filename="AI SDK 4.0"
+const { messages } = useChat({
+  keepLastMessageOnError: true,
+});
+```
+
+```tsx filename="AI SDK 5.0"
+const { messages } = useChat({
+  // keepLastMessageOnError is no longer needed
+});
+```
+
+#### Chat Request Options Changes
+
+The `data` and `allowEmptySubmit` options have been removed from `ChatRequestOptions`.
+
+```tsx filename="AI SDK 4.0"
+handleSubmit(e, {
+  data: { imageUrl: 'https://...' },
+  body: { custom: 'value' },
+  allowEmptySubmit: true,
+});
+```
+
+```tsx filename="AI SDK 5.0"
+sendMessage(
+  {
+    /* yourMessage */
+  },
+  {
+    body: {
+      custom: 'value',
+      imageUrl: 'https://...', // Move data to body
+    },
+  },
+);
+```
+
+#### Request Options Type Rename
+
+`RequestOptions` has been renamed to `CompletionRequestOptions`.
+
+```tsx filename="AI SDK 4.0"
+import type { RequestOptions } from 'ai';
+```
+
+```tsx filename="AI SDK 5.0"
+import type { CompletionRequestOptions } from 'ai';
+```
+
+#### addToolResult Renamed to addToolOutput
+
+The `addToolResult` method has been renamed to `addToolOutput`. Additionally, the `result` parameter has been renamed to `output` for consistency with other tool-related APIs.
+
+```tsx filename="AI SDK 4.0"
+const { addToolResult } = useChat();
+
+// Add tool result with 'result' parameter
+addToolResult({
+  toolCallId: 'tool-call-123',
+  result: 'Weather: 72°F, sunny',
+});
+```
+
+```tsx filename="AI SDK 5.0"
+const { addToolOutput } = useChat();
+
+// Add tool output with 'output' parameter and 'tool' name for type safety
+addToolOutput({
+  tool: 'getWeather',
+  toolCallId: 'tool-call-123',
+  output: 'Weather: 72°F, sunny',
+});
+```
+
+<Note>
+  `addToolResult` is still available but deprecated. It will be removed in
+  version 6.
+</Note>
+
+#### Tool Result Submission Changes
+
+The automatic tool result submission behavior has been updated in `useChat` and the `Chat` component. You now have more control and flexibility over when tool results are submitted.
+
+- `onToolCall` no longer supports returning values to automatically submit tool results
+- You must explicitly call `addToolOutput` to provide tool results
+- Use `sendAutomaticallyWhen` with `lastAssistantMessageIsCompleteWithToolCalls` helper for automatic submission
+- Important: Don't use `await` with `addToolOutput` inside `onToolCall` to avoid deadlocks
+- The `maxSteps` parameter has been removed from the `Chat` component and `useChat` hook
+- For multi-step tool execution, use server-side `stopWhen` conditions instead (see [maxSteps Removal](#maxsteps-removal))
+
+```tsx filename="AI SDK 4.0"
+const { messages, sendMessage, addToolResult } = useChat({
+  maxSteps: 5, // Removed in v5
+
+  // Automatic submission by returning a value
+  async onToolCall({ toolCall }) {
+    if (toolCall.toolName === 'getLocation') {
+      const cities = ['New York', 'Los Angeles', 'Chicago', 'San Francisco'];
+      return cities[Math.floor(Math.random() * cities.length)];
+    }
+  },
+});
+```
+
+```tsx filename="AI SDK 5.0"
+import { useChat } from '@ai-sdk/react';
+import {
+  DefaultChatTransport,
+  lastAssistantMessageIsCompleteWithToolCalls,
+} from 'ai';
+
+const { messages, sendMessage, addToolOutput } = useChat({
+  // Automatic submission with helper
+  sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
+
+  async onToolCall({ toolCall }) {
+    if (toolCall.toolName === 'getLocation') {
+      const cities = ['New York', 'Los Angeles', 'Chicago', 'San Francisco'];
+
+      // Important: Don't await inside onToolCall to avoid deadlocks
+      addToolOutput({
+        tool: 'getLocation',
+        toolCallId: toolCall.toolCallId,
+        output: cities[Math.floor(Math.random() * cities.length)],
+      });
+    }
+  },
+});
+```
+
+#### Loading State Changes
+
+The deprecated `isLoading` helper has been removed in favor of `status`.
+
+```tsx filename="AI SDK 4.0"
+const { isLoading } = useChat();
+```
+
+```tsx filename="AI SDK 5.0"
+const { status } = useChat();
+// Use state instead of isLoading for more granular control
+```
+
+#### Resume Stream Support
+
+The resume functionality has been moved from `experimental_resume` to `resumeStream`.
+
+```tsx filename="AI SDK 4.0"
+// Resume was experimental
+const { messages } = useChat({
+  experimental_resume: true,
+});
+```
+
+```tsx filename="AI SDK 5.0"
+const { messages } = useChat({
+  resumeStream: true, // Resume interrupted streams
+});
+```
+
+#### Dynamic Body Values
+
+In v4, the `body` option in useChat configuration would dynamically update with component state changes. In v5, the `body` value is only captured at the first render and remains static throughout the component lifecycle.
+
+```tsx filename="AI SDK 4.0"
+const [temperature, setTemperature] = useState(0.7);
+
+const { messages } = useChat({
+  api: '/api/chat',
+  body: {
+    temperature, // This would update dynamically in v4
+  },
+});
+```
+
+```tsx filename="AI SDK 5.0"
+const [temperature, setTemperature] = useState(0.7);
+
+// Option 1: Use request-level configuration (Recommended)
+const { messages, sendMessage } = useChat({
+  transport: new DefaultChatTransport({ api: '/api/chat' }),
+});
+
+// Pass dynamic values at request time
+sendMessage(
+  { text: input },
+  {
+    body: {
+      temperature, // Current temperature value at request time
+    },
+  },
+);
+
+// Option 2: Use function configuration with useRef
+const temperatureRef = useRef(temperature);
+temperatureRef.current = temperature;
+
+const { messages } = useChat({
+  transport: new DefaultChatTransport({
+    api: '/api/chat',
+    body: () => ({
+      temperature: temperatureRef.current,
+    }),
+  }),
+});
+```
+
+For more details on request configuration, see the [Chatbot guide](/docs/ai-sdk-ui/chatbot#request-configuration).
+
+#### Usage Information
+
+In v4, usage information was directly accessible through the `onFinish` callback's options parameter. In v5, usage data is attached as metadata to individual messages using the `messageMetadata` function in `toUIMessageStreamResponse`.
+
+```tsx filename="AI SDK 4.0"
+const { messages } = useChat({
+  onFinish(message, options) {
+    const usage = options.usage;
+    console.log('Usage:', usage);
+  },
+});
+```
+
+```tsx filename="AI SDK 5.0"
+import {
+  convertToModelMessages,
+  streamText,
+  UIMessage,
+  type LanguageModelUsage,
+} from 'ai';
+__PROVIDER_IMPORT__;
+
+// Create a new metadata type (optional for type-safety)
+type MyMetadata = {
+  totalUsage: LanguageModelUsage;
+};
+
+// Create a new custom message type with your own metadata
+export type MyUIMessage = UIMessage<MyMetadata>;
+
+export async function POST(req: Request) {
+  const { messages }: { messages: MyUIMessage[] } = await req.json();
+
+  const result = streamText({
+    model: __MODEL__,
+    messages: convertToModelMessages(messages),
+  });
+
+  return result.toUIMessageStreamResponse({
+    originalMessages: messages,
+    messageMetadata: ({ part }) => {
+      // Send total usage when generation is finished
+      if (part.type === 'finish') {
+        return { totalUsage: part.totalUsage };
+      }
+    },
+  });
+}
+```
+
+Then, on the client, you can access the message-level metadata.
+
+```tsx filename="AI SDK 5.0 - Client"
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+import type { MyUIMessage } from './api/chat/route';
+import { DefaultChatTransport } from 'ai';
+
+export default function Chat() {
+  // Use custom message type defined on the server (optional for type-safety)
+  const { messages } = useChat<MyUIMessage>({
+    transport: new DefaultChatTransport({
+      api: '/api/chat',
+    }),
+  });
+
+  return (
+    <div className="flex flex-col w-full max-w-md py-24 mx-auto stretch">
+      {messages.map(m => (
+        <div key={m.id} className="whitespace-pre-wrap">
+          {m.role === 'user' ? 'User: ' : 'AI: '}
+          {m.parts.map(part => {
+            if (part.type === 'text') {
+              return part.text;
+            }
+          })}
+          {/* Render usage via metadata */}
+          {m.metadata?.totalUsage && (
+            <div>Total usage: {m.metadata?.totalUsage.totalTokens} tokens</div>
+          )}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+You can also access your metadata from the `onFinish` callback of `useChat`:
+
+```tsx filename="AI SDK 5.0 - onFinish"
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+import type { MyUIMessage } from './api/chat/route';
+import { DefaultChatTransport } from 'ai';
+
+export default function Chat() {
+  // Use custom message type defined on the server (optional for type-safety)
+  const { messages } = useChat<MyUIMessage>({
+    transport: new DefaultChatTransport({
+      api: '/api/chat',
+    }),
+    onFinish: ({ message }) => {
+      // Access message metadata via onFinish callback
+      console.log(message.metadata?.totalUsage);
+    },
+  });
+}
+```
+
+#### Request Body Preparation: experimental_prepareRequestBody → prepareSendMessagesRequest
+
+The `experimental_prepareRequestBody` option has been replaced with `prepareSendMessagesRequest` in the transport configuration.
+
+```tsx filename="AI SDK 4.0"
+import { useChat } from '@ai-sdk/react';
+
+const { messages } = useChat({
+  api: '/api/chat',
+  // Only send the last message to the server:
+  experimental_prepareRequestBody({ messages, id }) {
+    return { message: messages[messages.length - 1], id };
+  },
+});
+```
+
+```tsx filename="AI SDK 5.0"
+import { useChat } from '@ai-sdk/react';
+import { DefaultChatTransport } from 'ai';
+
+const { messages } = useChat({
+  transport: new DefaultChatTransport({
+    api: '/api/chat',
+    // Only send the last message to the server:
+    prepareSendMessagesRequest({ messages, id }) {
+      return { body: { message: messages[messages.length - 1], id } };
+    },
+  }),
+});
+```
+
+### `@ai-sdk/vue` Changes
+
+The Vue.js integration has been completely restructured, replacing the `useChat` composable with a `Chat` class.
+
+#### useChat Replaced with Chat Class
+
+```typescript filename="@ai-sdk/vue v1"
+<script setup>
+import { useChat } from '@ai-sdk/vue';
+
+const { messages, input, handleSubmit } = useChat({
+  api: '/api/chat',
+});
+</script>
+```
+
+```typescript filename="@ai-sdk/vue v2"
+<script setup>
+import { Chat } from '@ai-sdk/vue';
+import { DefaultChatTransport } from 'ai';
+import { ref } from 'vue';
+
+const input = ref('');
+const chat = new Chat({
+  transport: new DefaultChatTransport({ api: '/api/chat' }),
+});
+
+const handleSubmit = (e: Event) => {
+  e.preventDefault();
+  chat.sendMessage({ text: input.value });
+  input.value = '';
+};
+</script>
+```
+
+#### Message Structure Changes
+
+Messages now use a `parts` array instead of a `content` string.
+
+```typescript filename="@ai-sdk/vue v1"
+<template>
+  <div v-for="message in messages" :key="message.id">
+    <div>{{ message.role }}: {{ message.content }}</div>
+  </div>
+</template>
+```
+
+```typescript filename="@ai-sdk/vue v2"
+<template>
+  <div v-for="message in chat.messages" :key="message.id">
+    <div>{{ message.role }}:</div>
+    <div v-for="part in message.parts" :key="part.type">
+      <span v-if="part.type === 'text'">{{ part.text }}</span>
+    </div>
+  </div>
+</template>
+```
+
+### `@ai-sdk/svelte` Changes
+
+The Svelte integration has also been updated with new constructor patterns and readonly properties.
+
+#### Constructor API Changes
+
+```js filename="@ai-sdk/svelte v1"
+import { Chat } from '@ai-sdk/svelte';
+
+const chatInstance = Chat({
+  api: '/api/chat',
+});
+```
+
+```js filename="@ai-sdk/svelte v2"
+import { Chat } from '@ai-sdk/svelte';
+import { DefaultChatTransport } from 'ai';
+
+const chatInstance = Chat(() => ({
+  transport: new DefaultChatTransport({ api: '/api/chat' }),
+}));
+```
+
+##### Properties Made Readonly
+
+Properties are now readonly and must be updated using setter methods.
+
+```js filename="@ai-sdk/svelte v1"
+// Direct property mutation was allowed
+chatInstance.messages = [...chatInstance.messages, newMessage];
+```
+
+```js filename="@ai-sdk/svelte v2"
+// Must use setter methods
+chatInstance.setMessages([...chatInstance.messages, newMessage]);
+```
+
+##### Removed Managed Input
+
+Like React and Vue, input management has been removed from the Svelte integration.
+
+```js filename="@ai-sdk/svelte v1"
+// Input was managed internally
+const { messages, input, handleSubmit } = chatInstance;
+```
+
+```js filename="@ai-sdk/svelte v2"
+// Must manage input state manually
+let input = '';
+const { messages, sendMessage } = chatInstance;
+
+const handleSubmit = () => {
+  sendMessage({ text: input });
+  input = '';
+};
+```
+
+#### `@ai-sdk/ui-utils` Package Removal
+
+The `@ai-sdk/ui-utils` package has been removed and its exports moved to the main `ai` package.
+
+```tsx filename="AI SDK 4.0"
+import { getTextFromDataUrl } from '@ai-sdk/ui-utils';
+```
+
+```tsx filename="AI SDK 5.0"
+import { getTextFromDataUrl } from 'ai';
+```
+
+**Note**: `processDataStream` was removed entirely in v5.0. Use `readUIMessageStream` instead for processing UI message streams, or use the more configurable Chat/useChat APIs for most use cases.
+
+### useCompletion Changes
+
+The `data` property has been removed from the `useCompletion` hook.
+
+```tsx filename="AI SDK 4.0"
+const {
+  completion,
+  handleSubmit,
+  data, // No longer available
+} = useCompletion();
+```
+
+```tsx filename="AI SDK 5.0"
+const {
+  completion,
+  handleSubmit,
+  // data property removed entirely
+} = useCompletion();
+```
+
+### useAssistant Removal
+
+The `useAssistant` hook has been removed.
+
+```tsx filename="AI SDK 4.0"
+import { useAssistant } from '@ai-sdk/react';
+```
+
+```tsx filename="AI SDK 5.0"
+// useAssistant has been removed
+// Use useChat with appropriate configuration instead
+```
+
+For an implementation of the assistant functionality with AI SDK v5, see this [example repository](https://github.com/vercel-labs/ai-sdk-openai-assistants-api).
+
+#### Attachments → File Parts
+
+The `experimental_attachments` property has been replaced with the parts array.
+
+```tsx filename="AI SDK 4.0"
+{
+  messages.map(message => (
+    <div className="flex flex-col gap-2">
+      {message.content}
+
+      <div className="flex flex-row gap-2">
+        {message.experimental_attachments?.map((attachment, index) =>
+          attachment.contentType?.includes('image/') ? (
+            <img src={attachment.url} alt={attachment.name} />
+          ) : attachment.contentType?.includes('text/') ? (
+            <div className="w-32 h-24 p-2 overflow-hidden text-xs border rounded-md ellipsis text-zinc-500">
+              {getTextFromDataUrl(attachment.url)}
+            </div>
+          ) : null,
+        )}
+      </div>
+    </div>
+  ));
+}
+```
+
+```tsx filename="AI SDK 5.0"
+{
+  messages.map(message => (
+    <div>
+      {message.parts.map((part, index) => {
+        if (part.type === 'text') {
+          return <div key={index}>{part.text}</div>;
+        }
+
+        if (part.type === 'file' && part.mediaType?.startsWith('image/')) {
+          return (
+            <div key={index}>
+              <img src={part.url} />
+            </div>
+          );
+        }
+      })}
+    </div>
+  ));
+}
+```
+
+<Note>
+  Some models do not support text files (text/plain, text/markdown, text/csv,
+  etc.) as file parts. For text files, you can read and send the context as a text part
+  instead:
+
+```tsx
+// Instead of this:
+{ type: 'file', data: buffer, mediaType: 'text/plain' }
+
+// Do this:
+{ type: 'text', text: buffer.toString('utf-8') }
+```
+
+</Note>
+
+### Embedding Changes
+
+#### Provider Options for Embeddings
+
+Embedding model settings now use provider options instead of model parameters.
+
+```tsx filename="AI SDK 4.0"
+const { embedding } = await embed({
+  model: openai('text-embedding-3-small', {
+    dimensions: 10,
+  }),
+});
+```
+
+```tsx filename="AI SDK 5.0"
+const { embedding } = await embed({
+  model: openai('text-embedding-3-small'),
+  providerOptions: {
+    openai: {
+      dimensions: 10,
+    },
+  },
+});
+```
+
+#### Raw Response → Response
+
+The `rawResponse` property has been renamed to `response`.
+
+```tsx filename="AI SDK 4.0"
+const { rawResponse } = await embed(/* */);
+```
+
+```tsx filename="AI SDK 5.0"
+const { response } = await embed(/* */);
+```
+
+#### Parallel Requests in embedMany
+
+`embedMany` now makes parallel requests with a configurable `maxParallelCalls` option.
+
+```tsx filename="AI SDK 5.0"
+const { embeddings, usage } = await embedMany({
+  maxParallelCalls: 2, // Limit parallel requests
+  model: 'openai/text-embedding-3-small',
+  values: [
+    'sunny day at the beach',
+    'rainy afternoon in the city',
+    'snowy night in the mountains',
+  ],
+});
+```
+
+#### LangChain Adapter Moved to `@ai-sdk/langchain`
+
+The `LangChainAdapter` has been moved to `@ai-sdk/langchain` and the API has been updated to use UI message streams.
+
+```tsx filename="AI SDK 4.0"
+import { LangChainAdapter } from 'ai';
+
+const response = LangChainAdapter.toDataStreamResponse(stream);
+```
+
+```tsx filename="AI SDK 5.0"
+import { toUIMessageStream } from '@ai-sdk/langchain';
+import { createUIMessageStreamResponse } from 'ai';
+
+const response = createUIMessageStreamResponse({
+  stream: toUIMessageStream(stream),
+});
+```
+
+<Note>
+  Don't forget to install the new package: `npm install @ai-sdk/langchain`
+</Note>
+
+#### LlamaIndex Adapter Moved to `@ai-sdk/llamaindex`
+
+The `LlamaIndexAdapter` has been extracted to a separate package `@ai-sdk/llamaindex` and follows the same UI message stream pattern.
+
+```tsx filename="AI SDK 4.0"
+import { LlamaIndexAdapter } from 'ai';
+
+const response = LlamaIndexAdapter.toDataStreamResponse(stream);
+```
+
+```tsx filename="AI SDK 5.0"
+import { toUIMessageStream } from '@ai-sdk/llamaindex';
+import { createUIMessageStreamResponse } from 'ai';
+
+const response = createUIMessageStreamResponse({
+  stream: toUIMessageStream(stream),
+});
+```
+
+<Note>
+  Don't forget to install the new package: `npm install @ai-sdk/llamaindex`
+</Note>
+
+## Streaming Architecture
+
+The streaming architecture has been completely redesigned in v5 to support better content differentiation, concurrent streaming of multiple parts, and improved real-time UX.
+
+### Stream Protocol Changes
+
+#### Stream Protocol: Single Chunks → Start/Delta/End Pattern
+
+The fundamental streaming pattern has changed from single chunks to a three-phase pattern with unique IDs for each content block.
+
+```tsx filename="AI SDK 4.0"
+for await (const chunk of result.fullStream) {
+  switch (chunk.type) {
+    case 'text-delta': {
+      process.stdout.write(chunk.textDelta);
+      break;
+    }
+  }
+}
+```
+
+```tsx filename="AI SDK 5.0"
+for await (const chunk of result.fullStream) {
+  switch (chunk.type) {
+    case 'text-start': {
+      // New: Initialize a text block with unique ID
+      console.log(`Starting text block: ${chunk.id}`);
+      break;
+    }
+    case 'text-delta': {
+      // Changed: Now includes ID and uses 'delta' property
+      process.stdout.write(chunk.delta); // Changed from 'textDelta'
+      break;
+    }
+    case 'text-end': {
+      // New: Finalize the text block
+      console.log(`Completed text block: ${chunk.id}`);
+      break;
+    }
+  }
+}
+```
+
+#### Reasoning Streaming Pattern
+
+Reasoning content now follows the same start/delta/end pattern:
+
+```tsx filename="AI SDK 4.0"
+for await (const chunk of result.fullStream) {
+  switch (chunk.type) {
+    case 'reasoning': {
+      // Single chunk with full reasoning text
+      console.log('Reasoning:', chunk.text);
+      break;
+    }
+  }
+}
+```
+
+```tsx filename="AI SDK 5.0"
+for await (const chunk of result.fullStream) {
+  switch (chunk.type) {
+    case 'reasoning-start': {
+      console.log(`Starting reasoning block: ${chunk.id}`);
+      break;
+    }
+    case 'reasoning-delta': {
+      process.stdout.write(chunk.delta);
+      break;
+    }
+    case 'reasoning-end': {
+      console.log(`Completed reasoning block: ${chunk.id}`);
+      break;
+    }
+  }
+}
+```
+
+#### Tool Input Streaming
+
+Tool inputs can now be streamed as they're being generated:
+
+```tsx filename="AI SDK 5.0"
+for await (const chunk of result.fullStream) {
+  switch (chunk.type) {
+    case 'tool-input-start': {
+      console.log(`Starting tool input for ${chunk.toolName}: ${chunk.id}`);
+      break;
+    }
+    case 'tool-input-delta': {
+      // Stream the JSON input as it's being generated
+      process.stdout.write(chunk.delta);
+      break;
+    }
+    case 'tool-input-end': {
+      console.log(`Completed tool input: ${chunk.id}`);
+      break;
+    }
+    case 'tool-call': {
+      // Final tool call with complete input
+      console.log('Tool call:', chunk.toolName, chunk.input);
+      break;
+    }
+  }
+}
+```
+
+#### onChunk Callback Changes
+
+The `onChunk` callback now receives the new streaming chunk types with IDs and the start/delta/end pattern.
+
+```tsx filename="AI SDK 4.0"
+const result = streamText({
+  model: __MODEL__,
+  prompt: 'Write a story',
+  onChunk({ chunk }) {
+    switch (chunk.type) {
+      case 'text-delta': {
+        // Single property with text content
+        console.log('Text delta:', chunk.textDelta);
+        break;
+      }
+    }
+  },
+});
+```
+
+```tsx filename="AI SDK 5.0"
+const result = streamText({
+  model: __MODEL__,
+  prompt: 'Write a story',
+  onChunk({ chunk }) {
+    switch (chunk.type) {
+      case 'text-delta': {
+        // Text chunks now use single 'text' type
+        console.log('Text chunk:', chunk.text);
+        break;
+      }
+      case 'reasoning': {
+        // Reasoning chunks use single 'reasoning' type
+        console.log('Reasoning chunk:', chunk.text);
+        break;
+      }
+      case 'source': {
+        console.log('Source chunk:', chunk);
+        break;
+      }
+      case 'tool-call': {
+        console.log('Tool call:', chunk.toolName, chunk.input);
+        break;
+      }
+      case 'tool-input-start': {
+        console.log(
+          `Tool input started for ${chunk.toolName}:`,
+          chunk.toolCallId,
+        );
+        break;
+      }
+      case 'tool-input-delta': {
+        console.log(`Tool input delta for ${chunk.toolCallId}:`, chunk.delta);
+        break;
+      }
+      case 'tool-result': {
+        console.log('Tool result:', chunk.output);
+        break;
+      }
+      case 'raw': {
+        console.log('Raw chunk:', chunk);
+        break;
+      }
+    }
+  },
+});
+```
+
+#### File Stream Parts Restructure
+
+File parts in streams have been flattened.
+
+```tsx filename="AI SDK 4.0"
+for await (const chunk of result.fullStream) {
+  switch (chunk.type) {
+    case 'file': {
+      console.log('Media type:', chunk.file.mediaType);
+      console.log('File data:', chunk.file.data);
+      break;
+    }
+  }
+}
+```
+
+```tsx filename="AI SDK 5.0"
+for await (const chunk of result.fullStream) {
+  switch (chunk.type) {
+    case 'file': {
+      console.log('Media type:', chunk.mediaType);
+      console.log('File data:', chunk.data);
+      break;
+    }
+  }
+}
+```
+
+#### Source Stream Parts Restructure
+
+Source stream parts have been flattened.
+
+```tsx filename="AI SDK 4.0"
+for await (const part of result.fullStream) {
+  if (part.type === 'source' && part.source.sourceType === 'url') {
+    console.log('ID:', part.source.id);
+    console.log('Title:', part.source.title);
+    console.log('URL:', part.source.url);
+  }
+}
+```
+
+```tsx filename="AI SDK 5.0"
+for await (const part of result.fullStream) {
+  if (part.type === 'source' && part.sourceType === 'url') {
+    console.log('ID:', part.id);
+    console.log('Title:', part.title);
+    console.log('URL:', part.url);
+  }
+}
+```
+
+#### Finish Event Changes
+
+Stream finish events have been renamed for consistency.
+
+```tsx filename="AI SDK 4.0"
+for await (const part of result.fullStream) {
+  switch (part.type) {
+    case 'step-finish': {
+      console.log('Step finished:', part.finishReason);
+      break;
+    }
+    case 'finish': {
+      console.log('Usage:', part.usage);
+      break;
+    }
+  }
+}
+```
+
+```tsx filename="AI SDK 5.0"
+for await (const part of result.fullStream) {
+  switch (part.type) {
+    case 'finish-step': {
+      // Renamed from 'step-finish'
+      console.log('Step finished:', part.finishReason);
+      break;
+    }
+    case 'finish': {
+      console.log('Total Usage:', part.totalUsage); // Changed from 'usage'
+      break;
+    }
+  }
+}
+```
+
+### Stream Protocol Changes
+
+#### Proprietary Protocol -> Server-Sent Events
+
+The data stream protocol has been updated to use Server-Sent Events.
+
+```tsx filename="AI SDK 4.0"
+import { createDataStream, formatDataStreamPart } from 'ai';
+
+const dataStream = createDataStream({
+  execute: writer => {
+    writer.writeData('initialized call');
+    writer.write(formatDataStreamPart('text', 'Hello'));
+    writer.writeSource({
+      type: 'source',
+      sourceType: 'url',
+      id: 'source-1',
+      url: 'https://example.com',
+      title: 'Example Source',
+    });
+  },
+});
+```
+
+```tsx filename="AI SDK 5.0"
+import { createUIMessageStream } from 'ai';
+
+const stream = createUIMessageStream({
+  execute: ({ writer }) => {
+    writer.write({ type: 'data', value: ['initialized call'] });
+    writer.write({ type: 'text', value: 'Hello' });
+    writer.write({
+      type: 'source-url',
+      value: {
+        type: 'source',
+        id: 'source-1',
+        url: 'https://example.com',
+        title: 'Example Source',
+      },
+    });
+  },
+});
+```
+
+#### Data Stream Response Helper Functions Renamed
+
+The streaming API has been completely restructured from data streams to UI message streams.
+
+```tsx filename="AI SDK 4.0"
+// Express/Node.js servers
+app.post('/stream', async (req, res) => {
+  const result = streamText({
+    model: __MODEL__,
+    prompt: 'Generate content',
+  });
+
+  result.pipeDataStreamToResponse(res);
+});
+
+// Next.js API routes
+const result = streamText({
+  model: __MODEL__,
+  prompt: 'Generate content',
+});
+
+return result.toDataStreamResponse();
+```
+
+```tsx filename="AI SDK 5.0"
+// Express/Node.js servers
+app.post('/stream', async (req, res) => {
+  const result = streamText({
+    model: __MODEL__,
+    prompt: 'Generate content',
+  });
+
+  result.pipeUIMessageStreamToResponse(res);
+});
+
+// Next.js API routes
+const result = streamText({
+  model: __MODEL__,
+  prompt: 'Generate content',
+});
+
+return result.toUIMessageStreamResponse();
+```
+
+#### Stream Transform Function Renaming
+
+Various stream-related functions have been renamed for consistency.
+
+```tsx filename="AI SDK 4.0"
+import { DataStreamToSSETransformStream } from 'ai';
+```
+
+```tsx filename="AI SDK 5.0"
+import { JsonToSseTransformStream } from 'ai';
+```
+
+#### Error Handling: getErrorMessage → onError
+
+The `getErrorMessage` option in `toDataStreamResponse` has been replaced with `onError` in `toUIMessageStreamResponse`, providing more control over error forwarding to the client.
+
+By default, error messages are NOT sent to the client to prevent leaking sensitive information. The `onError` callback allows you to explicitly control what error information is forwarded to the client.
+
+```tsx filename="AI SDK 4.0"
+return result.toDataStreamResponse({
+  getErrorMessage: error => {
+    // Return sanitized error data to send to client
+    // Only return what you want the client to see!
+    return {
+      errorCode: 'STREAM_ERROR',
+      message: 'An error occurred while processing your request',
+      // In production, avoid sending error.message directly to prevent information leakage
+    };
+  },
+});
+```
+
+```tsx filename="AI SDK 5.0"
+return result.toUIMessageStreamResponse({
+  onError: error => {
+    // Return sanitized error data to send to client
+    // Only return what you want the client to see!
+    return {
+      errorCode: 'STREAM_ERROR',
+      message: 'An error occurred while processing your request',
+      // In production, avoid sending error.message directly to prevent information leakage
+    };
+  },
+});
+```
+
+### Utility Changes
+
+#### ID Generation Changes
+
+The `createIdGenerator()` function now requires a `size` argument.
+
+```tsx filename="AI SDK 4.0"
+const generator = createIdGenerator({ prefix: 'msg' });
+const id = generator(16); // Custom size at call time
+```
+
+```tsx filename="AI SDK 5.0"
+const generator = createIdGenerator({ prefix: 'msg', size: 16 });
+const id = generator(); // Fixed size from creation
+```
+
+#### IDGenerator → IdGenerator
+
+The type name has been updated.
+
+```tsx filename="AI SDK 4.0"
+import { IDGenerator } from 'ai';
+```
+
+```tsx filename="AI SDK 5.0"
+import { IdGenerator } from 'ai';
+```
+
+### Provider Interface Changes
+
+#### Language Model V2 Import
+
+`LanguageModelV3` must now be imported from `@ai-sdk/provider`.
+
+```tsx filename="AI SDK 4.0"
+import { LanguageModelV3 } from 'ai';
+```
+
+```tsx filename="AI SDK 5.0"
+import { LanguageModelV3 } from '@ai-sdk/provider';
+```
+
+#### Middleware Rename
+
+`LanguageModelV1Middleware` has been renamed and moved.
+
+```tsx filename="AI SDK 4.0"
+import { LanguageModelV1Middleware } from 'ai';
+```
+
+```tsx filename="AI SDK 5.0"
+import { LanguageModelV3Middleware } from '@ai-sdk/provider';
+```
+
+#### Usage Token Properties
+
+Token usage properties have been renamed for consistency.
+
+```tsx filename="AI SDK 4.0"
+// In language model implementations
+{
+  usage: {
+    promptTokens: 10,
+    completionTokens: 20
+  }
+}
+```
+
+```tsx filename="AI SDK 5.0"
+// In language model implementations
+{
+  usage: {
+    inputTokens: 10,
+    outputTokens: 20,
+    totalTokens: 30 // Now required
+  }
+}
+```
+
+#### Stream Part Type Changes
+
+The `LanguageModelV3StreamPart` type has been expanded to support the new streaming architecture with start/delta/end patterns and IDs.
+
+```tsx filename="AI SDK 4.0"
+// V4: Simple stream parts
+type LanguageModelV3StreamPart =
+  | { type: 'text-delta'; textDelta: string }
+  | { type: 'reasoning'; text: string }
+  | { type: 'tool-call'; toolCallId: string; toolName: string; input: string };
+```
+
+```tsx filename="AI SDK 5.0"
+// V5: Enhanced stream parts with IDs and lifecycle events
+type LanguageModelV3StreamPart =
+  // Text blocks with start/delta/end pattern
+  | {
+      type: 'text-start';
+      id: string;
+      providerMetadata?: SharedV2ProviderMetadata;
+    }
+  | {
+      type: 'text-delta';
+      id: string;
+      delta: string;
+      providerMetadata?: SharedV2ProviderMetadata;
+    }
+  | {
+      type: 'text-end';
+      id: string;
+      providerMetadata?: SharedV2ProviderMetadata;
+    }
+
+  // Reasoning blocks with start/delta/end pattern
+  | {
+      type: 'reasoning-start';
+      id: string;
+      providerMetadata?: SharedV2ProviderMetadata;
+    }
+  | {
+      type: 'reasoning-delta';
+      id: string;
+      delta: string;
+      providerMetadata?: SharedV2ProviderMetadata;
+    }
+  | {
+      type: 'reasoning-end';
+      id: string;
+      providerMetadata?: SharedV2ProviderMetadata;
+    }
+
+  // Tool input streaming
+  | {
+      type: 'tool-input-start';
+      id: string;
+      toolName: string;
+      providerMetadata?: SharedV2ProviderMetadata;
+    }
+  | {
+      type: 'tool-input-delta';
+      id: string;
+      delta: string;
+      providerMetadata?: SharedV2ProviderMetadata;
+    }
+  | {
+      type: 'tool-input-end';
+      id: string;
+      providerMetadata?: SharedV2ProviderMetadata;
+    }
+
+  // Enhanced tool calls
+  | {
+      type: 'tool-call';
+      toolCallId: string;
+      toolName: string;
+      input: string;
+      providerMetadata?: SharedV2ProviderMetadata;
+    }
+
+  // Stream lifecycle events
+  | { type: 'stream-start'; warnings: Array<SharedV3Warning> }
+  | {
+      type: 'finish';
+      usage: LanguageModelV3Usage;
+      finishReason: LanguageModelV3FinishReason;
+      providerMetadata?: SharedV2ProviderMetadata;
+    };
+```
+
+#### Raw Response → Response
+
+Provider response objects have been updated.
+
+```tsx filename="AI SDK 4.0"
+// In language model implementations
+{
+  rawResponse: {
+    /* ... */
+  }
+}
+```
+
+```tsx filename="AI SDK 5.0"
+// In language model implementations
+{
+  response: {
+    /* ... */
+  }
+}
+```
+
+#### `wrapLanguageModel` now stable
+
+```tsx filename="AI SDK 4.0"
+import { experimental_wrapLanguageModel } from 'ai';
+```
+
+```tsx filename="AI SDK 5.0"
+import { wrapLanguageModel } from 'ai';
+```
+
+#### `activeTools` No Longer Experimental
+
+```tsx filename="AI SDK 4.0"
+const result = await generateText({
+  model: __MODEL__,
+  messages,
+  tools: { weatherTool, locationTool },
+  experimental_activeTools: ['weatherTool'],
+});
+```
+
+```tsx filename="AI SDK 5.0"
+const result = await generateText({
+  model: __MODEL__,
+  messages,
+  tools: { weatherTool, locationTool },
+  activeTools: ['weatherTool'], // No longer experimental
+});
+```
+
+#### `prepareStep` No Longer Experimental
+
+The `experimental_prepareStep` option has been promoted and no longer requires the experimental prefix.
+
+```tsx filename="AI SDK 4.0"
+const result = await generateText({
+  model: __MODEL__,
+  messages,
+  tools: { weatherTool, locationTool },
+  experimental_prepareStep: ({ steps, stepNumber, model }) => {
+    console.log('Preparing step:', stepNumber);
+    return {
+      activeTools: ['weatherTool'],
+      system: 'Be helpful and concise.',
+    };
+  },
+});
+```
+
+```tsx filename="AI SDK 5.0"
+const result = await generateText({
+  model: __MODEL__,
+  messages,
+  tools: { weatherTool, locationTool },
+  prepareStep: ({ steps, stepNumber, model }) => {
+    console.log('Preparing step:', stepNumber);
+    return {
+      activeTools: ['weatherTool'],
+      system: 'Be helpful and concise.',
+      // Can also configure toolChoice, model, etc.
+    };
+  },
+});
+```
+
+The `prepareStep` function receives `{ steps, stepNumber, model }` and can return:
+
+- `model`: Different model for this step
+- `activeTools`: Which tools to make available
+- `toolChoice`: Tool selection strategy
+- `system`: System message for this step
+- `undefined`: Use default settings
+
+### Temperature Default Removal
+
+Temperature is no longer set to `0` by default.
+
+```tsx filename="AI SDK 4.0"
+await generateText({
+  model: __MODEL__,
+  prompt: 'Write a creative story',
+  // Implicitly temperature: 0
+});
+```
+
+```tsx filename="AI SDK 5.0"
+await generateText({
+  model: __MODEL__,
+  prompt: 'Write a creative story',
+  temperature: 0, // Must explicitly set
+});
+```
+
+## Message Persistence Changes
+
+<Note>
+  If you have persisted messages in a database, see the [Data Migration
+  Guide](/docs/migration-guides/migration-guide-5-0-data) for comprehensive
+  guidance on migrating your stored message data to the v5 format.
+</Note>
+
+In v4, you would typically use helper functions like `appendResponseMessages` or `appendClientMessage` to format messages in the `onFinish` callback of `streamText`:
+
+```tsx filename="AI SDK 4.0"
+import {
+  streamText,
+  convertToModelMessages,
+  appendClientMessage,
+  appendResponseMessages,
+} from 'ai';
+
+const updatedMessages = appendClientMessage({
+  messages,
+  message: lastUserMessage,
+});
+
+const result = streamText({
+  model: __MODEL__,
+  messages: updatedMessages,
+  experimental_generateMessageId: () => generateId(), // ID generation on streamText
+  onFinish: async ({ responseMessages, usage }) => {
+    // Use helper functions to format messages
+    const finalMessages = appendResponseMessages({
+      messages: updatedMessages,
+      responseMessages,
+    });
+
+    // Save formatted messages to database
+    await saveMessages(finalMessages);
+  },
+});
+```
+
+In v5, message persistence is now handled through the `toUIMessageStreamResponse` method, which automatically formats response messages in the `UIMessage` format:
+
+```tsx filename="AI SDK 5.0"
+import { streamText, convertToModelMessages, UIMessage } from 'ai';
+
+const messages: UIMessage[] = [
+  // Your existing messages in UIMessage format
+];
+
+const result = streamText({
+  model: __MODEL__,
+  messages: convertToModelMessages(messages),
+  // experimental_generateMessageId removed from here
+});
+
+return result.toUIMessageStreamResponse({
+  originalMessages: messages, // IMPORTANT: Required to prevent duplicate messages
+  generateMessageId: () => generateId(), // IMPORTANT: Required for proper message ID generation
+  onFinish: ({ messages, responseMessage }) => {
+    // messages contains all messages (original + response) in UIMessage format
+    saveChat({ chatId, messages });
+
+    // responseMessage contains just the generated message in UIMessage format
+    saveMessage({ chatId, message: responseMessage });
+  },
+});
+```
+
+<Note>
+  **Important:** When using `toUIMessageStreamResponse`, you should always
+  provide both `originalMessages` and `generateMessageId` parameters. Without
+  these, you may experience duplicate or repeated assistant messages in your UI.
+  For more details, see [Troubleshooting: Repeated Assistant
+  Messages](/docs/troubleshooting/repeated-assistant-messages).
+</Note>
+
+### Message ID Generation
+
+The `experimental_generateMessageId` option has been moved from `streamText` configuration to `toUIMessageStreamResponse`, as it's designed for use with `UIMessage`s rather than `ModelMessage`s.
+
+```tsx filename="AI SDK 4.0"
+const result = streamText({
+  model: __MODEL__,
+  messages,
+  experimental_generateMessageId: () => generateId(),
+});
+```
+
+```tsx filename="AI SDK 5.0"
+const result = streamText({
+  model: __MODEL__,
+  messages: convertToModelMessages(messages),
+});
+
+return result.toUIMessageStreamResponse({
+  generateMessageId: () => generateId(), // No longer experimental
+  // ...
+});
+```
+
+For more details on message IDs and persistence, see the [Chatbot Message Persistence guide](/docs/ai-sdk-ui/chatbot-message-persistence#message-ids).
+
+### Using createUIMessageStream
+
+For more complex scenarios, especially when working with data parts, you can use `createUIMessageStream`:
+
+```tsx filename="AI SDK 5.0 - Advanced"
+import {
+  createUIMessageStream,
+  createUIMessageStreamResponse,
+  streamText,
+  convertToModelMessages,
+  UIMessage,
+} from 'ai';
+
+const stream = createUIMessageStream({
+  originalMessages: messages,
+  generateId: generateId, // Required for proper message ID generation
+  execute: ({ writer }) => {
+    // Write custom data parts
+    writer.write({
+      type: 'data',
+      data: { status: 'processing', timestamp: Date.now() },
+    });
+
+    // Stream the AI response
+    const result = streamText({
+      model: __MODEL__,
+      messages: convertToModelMessages(messages),
+    });
+
+    writer.merge(result.toUIMessageStream());
+  },
+  onFinish: ({ messages }) => {
+    // messages contains all messages (original + response + data parts) in UIMessage format
+    saveChat({ chatId, messages });
+  },
+});
+
+return createUIMessageStreamResponse({ stream });
+```
+
+## Provider & Model Changes
+
+### OpenAI
+
+#### Default Provider Instance Uses Responses API
+
+In AI SDK 5, the default OpenAI provider instance uses the Responses API, while AI SDK 4 used the Chat Completions API. The Chat Completions API remains fully supported and you can use it with `openai.chat(...)`.
+
+```tsx filename="AI SDK 4.0"
+import { openai } from '@ai-sdk/openai';
+
+const defaultModel = openai('gpt-4.1-mini'); // Chat Completions API
+```
+
+```tsx filename="AI SDK 5.0"
+import { openai } from '@ai-sdk/openai';
+
+const defaultModel = openai('gpt-4.1-mini'); // Responses API
+
+// Specify a specific API when needed:
+const chatCompletionsModel = openai.chat('gpt-4.1-mini');
+const responsesModel = openai.responses('gpt-4.1-mini');
+```
+
+<Note>
+  The Responses and Chat Completions APIs have different behavior and defaults.
+  If you depend on the Chat Completions API, switch your model instance to
+  `openai.chat(...)` and audit your configuration.
+</Note>
+
+#### Strict Schemas (`strictSchemas`) with Responses API
+
+In AI SDK 4.0, you could set the `strictSchemas` option on Responses models (which defaulted to `true`). This option has been renamed to `strictJsonSchema` in AI SDK 5.0 and now defaults to `false`.
+
+```tsx filename="AI SDK 4.0"
+import { z } from 'zod';
+import { generateObject } from 'ai';
+import { openai, type OpenAIResponsesProviderOptions } from '@ai-sdk/openai';
+
+const result = await generateObject({
+  model: openai.responses('gpt-4.1'),
+  schema: z.object({
+    // ...
+  }),
+  providerOptions: {
+    openai: {
+      strictSchemas: true, // default behaviour in AI SDK 4
+    } satisfies OpenAIResponsesProviderOptions,
+  },
+});
+```
+
+```tsx filename="AI SDK 5.0"
+import { z } from 'zod';
+import { generateObject } from 'ai';
+import { openai, type OpenAIResponsesProviderOptions } from '@ai-sdk/openai';
+
+const result = await generateObject({
+  model: openai('gpt-4.1-2024'), // uses Responses API
+  schema: z.object({
+    // ...
+  }),
+  providerOptions: {
+    openai: {
+      strictJsonSchema: true, // defaults to false, opt back in to the AI SDK 4 strict behaviour
+    } satisfies OpenAIResponsesProviderOptions,
+  },
+});
+```
+
+If you call `openai.chat(...)` to use the Chat Completions API directly, you can type it with `OpenAIChatLanguageModelOptions`. AI SDK 5 adds the same `strictJsonSchema` option there as well.
+
+#### Structured Outputs
+
+The `structuredOutputs` option is now configured using provider options rather than as a setting on the model instance.
+
+```tsx filename="AI SDK 4.0"
+import { z } from 'zod';
+import { generateObject } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+const result = await generateObject({
+  model: openai('gpt-4.1', { structuredOutputs: true }), // use Chat Completions API
+  schema: z.object({ name: z.string() }),
+});
+```
+
+```tsx filename="AI SDK 5.0 (Chat Completions API)"
+import { z } from 'zod';
+import { generateObject } from 'ai';
+import { openai, type OpenAIChatLanguageModelOptions } from '@ai-sdk/openai';
+
+const result = await generateObject({
+  model: openai.chat('gpt-4.1'), // use Chat Completions API
+  schema: z.object({ name: z.string() }),
+  providerOptions: {
+    openai: {
+      structuredOutputs: true,
+    } satisfies OpenAIChatLanguageModelOptions,
+  },
+});
+```
+
+#### Compatibility Option Removal
+
+The `compatibility` option has been removed; strict compatibility mode is now the default.
+
+```tsx filename="AI SDK 4.0"
+const openai = createOpenAI({
+  compatibility: 'strict',
+});
+```
+
+```tsx filename="AI SDK 5.0"
+const openai = createOpenAI({
+  // strict compatibility is now the default
+});
+```
+
+#### Legacy Function Calls Removal
+
+The `useLegacyFunctionCalls` option has been removed.
+
+```tsx filename="AI SDK 4.0"
+const result = streamText({
+  model: openai('gpt-4.1', { useLegacyFunctionCalls: true }),
+});
+```
+
+```tsx filename="AI SDK 5.0"
+const result = streamText({
+  model: openai('gpt-4.1'),
+});
+```
+
+#### Simulate Streaming
+
+The `simulateStreaming` model option has been replaced with middleware.
+
+```tsx filename="AI SDK 4.0"
+const result = generateText({
+  model: openai('gpt-4.1', { simulateStreaming: true }),
+  prompt: 'Hello, world!',
+});
+```
+
+```tsx filename="AI SDK 5.0"
+import { simulateStreamingMiddleware, wrapLanguageModel } from 'ai';
+
+const model = wrapLanguageModel({
+  model: openai('gpt-4.1'),
+  middleware: simulateStreamingMiddleware(),
+});
+
+const result = generateText({
+  model,
+  prompt: 'Hello, world!',
+});
+```
+
+### Google
+
+#### Search Grounding is now a provider defined tool
+
+Search Grounding is now called "Google Search" and is now a provider defined tool.
+
+```tsx filename="AI SDK 4.0"
+const { text, providerMetadata } = await generateText({
+  model: google('gemini-1.5-pro', {
+    useSearchGrounding: true,
+  }),
+  prompt: 'List the top 5 San Francisco news from the past week.',
+});
+```
+
+```tsx filename="AI SDK 5.0"
+import { google } from '@ai-sdk/google';
+const { text, sources, providerMetadata } = await generateText({
+  model: google('gemini-1.5-pro'),
+  prompt:
+    'List the top 5 San Francisco news from the past week.'
+  tools: {
+    google_search: google.tools.googleSearch({}),
+  },
+});
+```
+
+### Amazon Bedrock
+
+#### Snake Case → Camel Case
+
+Provider options have been updated to use camelCase.
+
+```tsx filename="AI SDK 4.0"
+const result = await generateText({
+  model: bedrock('amazon.titan-tg1-large'),
+  prompt: 'Hello, world!',
+  providerOptions: {
+    bedrock: {
+      reasoning_config: {
+        /* ... */
+      },
+    },
+  },
+});
+```
+
+```tsx filename="AI SDK 5.0"
+const result = await generateText({
+  model: bedrock('amazon.titan-tg1-large'),
+  prompt: 'Hello, world!',
+  providerOptions: {
+    bedrock: {
+      reasoningConfig: {
+        /* ... */
+      },
+    },
+  },
+});
+```
+
+### Provider-Utils Changes
+
+Deprecated `CoreTool*` types have been removed.
+
+```tsx filename="AI SDK 4.0"
+import {
+  CoreToolCall,
+  CoreToolResult,
+  CoreToolResultUnion,
+  CoreToolCallUnion,
+  CoreToolChoice,
+} from '@ai-sdk/provider-utils';
+```
+
+```tsx filename="AI SDK 5.0"
+import {
+  ToolCall,
+  ToolResult,
+  TypedToolResult,
+  TypedToolCall,
+  ToolChoice,
+} from '@ai-sdk/provider-utils';
+```
+
+## Troubleshooting
+
+### TypeScript Performance Issues with Zod
+
+If you experience TypeScript server crashes, slow type checking, or errors like "Type instantiation is excessively deep and possibly infinite" when using Zod with AI SDK 5.0:
+
+1. **First, ensure you're using Zod 4.1.8 or later** - this version includes a fix for module resolution issues that cause TypeScript performance problems.
+
+2. If the issue persists, update your `tsconfig.json` to use `moduleResolution: "nodenext"`:
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "nodenext"
+    // ... other options
+  }
+}
+```
+
+This resolves the TypeScript performance issues while allowing you to continue using the standard Zod import. If this doesn't resolve the issue, you can try using a version-specific import path as an alternative solution. For detailed troubleshooting steps, see [TypeScript performance issues with Zod](/docs/troubleshooting/typescript-performance-zod).
+
+## Codemod Table
+
+The following table lists available codemods for the AI SDK 5.0 upgrade
+process.
+For more information, see the [Codemods](#codemods) section.
+
+| Change                                           | Codemod                                               |
+| ------------------------------------------------ | ----------------------------------------------------- |
+| **AI SDK Core Changes**                          |                                                       |
+| Flatten streamText file properties               | `v5/flatten-streamtext-file-properties`               |
+| ID Generation Changes                            | `v5/require-createIdGenerator-size-argument`          |
+| IDGenerator → IdGenerator                        | `v5/rename-IDGenerator-to-IdGenerator`                |
+| Import LanguageModelV3 from provider package     | `v5/import-LanguageModelV3-from-provider-package`     |
+| Migrate to data stream protocol v2               | `v5/migrate-to-data-stream-protocol-v2`               |
+| Move image model maxImagesPerCall                | `v5/move-image-model-maxImagesPerCall`                |
+| Move LangChain adapter                           | `v5/move-langchain-adapter`                           |
+| Move maxSteps to stopWhen                        | `v5/move-maxsteps-to-stopwhen`                        |
+| Move provider options                            | `v5/move-provider-options`                            |
+| Move React to AI SDK                             | `v5/move-react-to-ai-sdk`                             |
+| Move UI utils to AI                              | `v5/move-ui-utils-to-ai`                              |
+| Remove experimental wrap language model          | `v5/remove-experimental-wrap-language-model`          |
+| Remove experimental activeTools                  | `v5/remove-experimental-activetools`                  |
+| Remove experimental prepareStep                  | `v5/remove-experimental-preparestep`                  |
+| Remove experimental continueSteps                | `v5/remove-experimental-continuesteps`                |
+| Remove experimental temperature                  | `v5/remove-experimental-temperature`                  |
+| Remove experimental truncate                     | `v5/remove-experimental-truncate`                     |
+| Remove experimental OpenAI compatibility         | `v5/remove-experimental-openai-compatibility`         |
+| Remove experimental OpenAI legacy function calls | `v5/remove-experimental-openai-legacy-function-calls` |
+| Remove experimental OpenAI structured outputs    | `v5/remove-experimental-openai-structured-outputs`    |
+| Remove experimental OpenAI store                 | `v5/remove-experimental-openai-store`                 |
+| Remove experimental OpenAI user                  | `v5/remove-experimental-openai-user`                  |
+| Remove experimental OpenAI parallel tool calls   | `v5/remove-experimental-openai-parallel-tool-calls`   |
+| Remove experimental OpenAI response format       | `v5/remove-experimental-openai-response-format`       |
+| Remove experimental OpenAI logit bias            | `v5/remove-experimental-openai-logit-bias`            |
+| Remove experimental OpenAI logprobs              | `v5/remove-experimental-openai-logprobs`              |
+| Remove experimental OpenAI seed                  | `v5/remove-experimental-openai-seed`                  |
+| Remove experimental OpenAI service tier          | `v5/remove-experimental-openai-service-tier`          |
+| Remove experimental OpenAI top logprobs          | `v5/remove-experimental-openai-top-logprobs`          |
+| Remove experimental OpenAI transform             | `v5/remove-experimental-openai-transform`             |
+| Remove experimental OpenAI stream options        | `v5/remove-experimental-openai-stream-options`        |
+| Remove experimental OpenAI prediction            | `v5/remove-experimental-openai-prediction`            |
+| Remove experimental Anthropic caching            | `v5/remove-experimental-anthropic-caching`            |
+| Remove experimental Anthropic computer use       | `v5/remove-experimental-anthropic-computer-use`       |
+| Remove experimental Anthropic PDF support        | `v5/remove-experimental-anthropic-pdf-support`        |
+| Remove experimental Anthropic prompt caching     | `v5/remove-experimental-anthropic-prompt-caching`     |
+| Remove experimental Google search grounding      | `v5/remove-experimental-google-search-grounding`      |
+| Remove experimental Google code execution        | `v5/remove-experimental-google-code-execution`        |
+| Remove experimental Google cached content        | `v5/remove-experimental-google-cached-content`        |
+| Remove experimental Google custom headers        | `v5/remove-experimental-google-custom-headers`        |
+| Rename format stream part                        | `v5/rename-format-stream-part`                        |
+| Rename parse stream part                         | `v5/rename-parse-stream-part`                         |
+| Replace image type with file type                | `v5/replace-image-type-with-file-type`                |
+| Replace LlamaIndex adapter                       | `v5/replace-llamaindex-adapter`                       |
+| Replace onCompletion with onFinal                | `v5/replace-oncompletion-with-onfinal`                |
+| Replace provider metadata with provider options  | `v5/replace-provider-metadata-with-provider-options`  |
+| Replace rawResponse with response                | `v5/replace-rawresponse-with-response`                |
+| Replace redacted reasoning type                  | `v5/replace-redacted-reasoning-type`                  |
+| Replace simulate streaming                       | `v5/replace-simulate-streaming`                       |
+| Replace textDelta with text                      | `v5/replace-textdelta-with-text`                      |
+| Replace usage token properties                   | `v5/replace-usage-token-properties`                   |
+| Restructure file stream parts                    | `v5/restructure-file-stream-parts`                    |
+| Restructure source stream parts                  | `v5/restructure-source-stream-parts`                  |
+| RSC package                                      | `v5/rsc-package`                                      |
+
+## Changes Between v5 Beta Versions
+
+This section documents breaking changes between different beta versions of AI SDK 5.0. If you're upgrading from an earlier v5 beta version to a later one, check this section for any changes that might affect your code.
+
+### fullStream Type Rename: text/reasoning → text-delta/reasoning-delta
+
+The chunk types in `fullStream` have been renamed for consistency with UI streams and language model streams.
+
+```tsx filename="AI SDK 5.0 (before beta.26)"
+for await (const chunk of result.fullStream) {
+  switch (chunk.type) {
+    case 'text-delta': {
+      process.stdout.write(chunk.text);
+      break;
+    }
+    case 'reasoning': {
+      console.log('Reasoning:', chunk.text);
+      break;
+    }
+  }
+}
+```
+
+```tsx filename="AI SDK 5.0 (beta.26 and later)"
+for await (const chunk of result.fullStream) {
+  switch (chunk.type) {
+    case 'text-delta': {
+      process.stdout.write(chunk.text);
+      break;
+    }
+    case 'reasoning-delta': {
+      console.log('Reasoning:', chunk.text);
+      break;
+    }
+  }
+}
+```