Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cloudflare/agents/llms.txt

Use this file to discover all available pages before exploring further.

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: 
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

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

​
Tool definitions: parameters to inputSchema

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: 
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

Build docs developers (and LLMs) love

Get started for freeTalk to us