Migrating to AI SDK v5

Upgrade guide for migrating from AI SDK v4 to v5 with @cloudflare/ai-chat

This guide covers the changes needed when upgrading from AI SDK v4 to v5 with @cloudflare/ai-chat.

If you are on AI SDK v5 and upgrading to v6, see the v6 migration guide instead.

Message format: content to parts

The biggest change. Messages now use a parts array instead of a content string:

v4

const message = { id: "1", role: "user", content: "Hello" };

You do not need to migrate stored messages manually. AIChatAgent automatically transforms legacy messages on load via autoTransformMessages(). This handles v4 content strings, tool invocations, reasoning parts, file data, and malformed formats.

Import changes

v4

import type { Message } from "ai";
import { useChat } from "ai/react";

Tool definitions: parameters to inputSchema

v4

const tools = {
  weather: {
    description: "Get weather",
    parameters: z.object({ city: z.string() }),
    execute: async ({ city }) => fetchWeather(city)
  }
};

Streaming events

v5 adds text-start and text-end events around text deltas, and renames textDelta to delta:

v4

chunk.type === "text-delta" && chunk.textDelta;

Migration checklist

1. Update dependencies

   npm update agents ai
   
2. Update type imports

   Replace import type { Message } with import type { UIMessage }

3. Update React imports

   Replace "ai/react" imports with "@ai-sdk/react"

4. Update tool definitions

   Rename parameters to inputSchema in tool definitions

5. Type check

   npm run typecheck
   

   Fix any remaining type errors

6. Test your application

   Legacy stored messages are migrated automatically

Migration utilities (deprecated)

These are available but rarely needed since migration is automatic:

import {
  autoTransformMessages, // Used internally by AIChatAgent
  migrateMessagesToUIFormat, // Deprecated -- use autoTransformMessages
  analyzeCorruption // Deprecated -- debugging only
} from "@cloudflare/ai-chat/ai-chat-v5-migration";

Further reading

• Official AI SDK v5 migration guide
• v6 migration guide (if upgrading further)