```
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),
});
```
For more information about model messages, see the [Model Message
reference](/docs/reference/ai-sdk-core/model-message).
### 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 (
{part.reasoning}
);
}
});
}
```
```tsx filename="AI SDK 5.0"
{
message.parts.map((part, index) => {
if (part.type === 'reasoning') {
return (
{part.text}
);
}
});
}
```
### File Part Changes
File parts now use `.url` instead of `.data` and `.mimeType`.
```tsx filename="AI SDK 4.0"
{
messages.map(message => (
{message.parts.map((part, index) => {
if (part.type === 'text') {
return
{part.text}
;
} else if (part.type === 'file' && part.mimeType.startsWith('image/')) {
return (
);
}
})}
{message.parts.map((part, index) => {
if (part.type === 'text') {
return
{part.text}
;
} else if (
part.type === 'file' &&
part.mediaType.startsWith('image/')
) {
return
;
}
})}
{part.toolInvocation.toolName}
;
}
});
}
```
```tsx filename="AI SDK 5.0"
// Type-safe tool parts with specific names
{
message.parts.map(part => {
switch (part.type) {
case 'tool-getWeatherInformation':
return Getting weather...
;
case 'tool-askForConfirmation':
return Asking for confirmation...
;
}
});
}
```
### 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 Weather: {part.input.city}
;
// Dynamic tools use the generic dynamic-tool type
case 'dynamic-tool':
return (
Dynamic tool: {part.toolName}
{JSON.stringify(part.input, null, 2)}
Loading...
;
case 'call':
return (
Tool called with {JSON.stringify(part.toolInvocation.args)}
);
case 'result':
return Result: {part.toolInvocation.result}
;
}
}
});
}
```
```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 {JSON.stringify(part.input, null, 2)};
case 'input-available':
return Getting weather for {part.input.city}...
;
case 'output-available':
return Weather: {part.output}
;
case 'output-error':
return Error: {part.errorText}
;
}
}
});
}
```
**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 {part.text}
;
case 'tool-invocation':
const { toolInvocation } = part;
return (
{toolInvocation.toolName}
{toolInvocation.state === 'result' ? (
Click to expand
) : (
calling...
)}
{toolInvocation.state === 'result' ? (
{JSON.stringify(toolInvocation.result, null, 2)}
) : null}
);
}
});
}
```
```tsx filename="AI SDK 5.0"
import { isToolUIPart, getToolName } from 'ai';
{
message.parts.map((part, index) => {
switch (part.type) {
case 'text':
return {part.text}
;
default:
if (isToolUIPart(part)) {
const toolInvocation = part;
return (
{getToolName(toolInvocation)}
{toolInvocation.state === 'output-available' ? (
Click to expand
) : (
calling...
)}
{toolInvocation.state === 'output-available' ? (
{JSON.stringify(toolInvocation.output, null, 2)}
) : null}
);
}
}
});
}
```
#### 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';
```
Don't forget to install the new package: `npm install @ai-sdk/rsc`
### 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';
```
Don't forget to install the new package: `npm install @ai-sdk/react`
### 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,
});
},
});
```
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()`.
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](/cookbook/next/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 (
);
}
```
```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 (
);
}
```
#### 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',
});
```
`addToolResult` is still available but deprecated. It will be removed in
version 6.
#### 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;
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({
transport: new DefaultChatTransport({
api: '/api/chat',
}),
});
return (
{messages.map(m => (
{m.role === 'user' ? 'User: ' : 'AI: '}
{m.parts.map(part => {
if (part.type === 'text') {
return part.text;
}
})}
{/* Render usage via metadata */}
{m.metadata?.totalUsage && (
Total usage: {m.metadata?.totalUsage.totalTokens} tokens
)}
))}
{{ message.role }}: {{ message.content }}
```
```typescript filename="@ai-sdk/vue v2"
{{ message.role }}:
{{ part.text }}
```
### `@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 => (
{message.content}
{message.experimental_attachments?.map((attachment, index) =>
attachment.contentType?.includes('image/') ? (
) : attachment.contentType?.includes('text/') ? (
{getTextFromDataUrl(attachment.url)}
) : null,
)}
{message.parts.map((part, index) => {
if (part.type === 'text') {
return
{part.text}
;
}
if (part.type === 'file' && part.mediaType?.startsWith('image/')) {
return (
);
}
})}