Skip to content

migration-to-ai-sdk-v6.md

Latest commit

 

History

History
163 lines (126 loc) · 5.04 KB

migration-to-ai-sdk-v6.md

File metadata and controls

163 lines (126 loc) · 5.04 KB

Migrating from AI SDK v5 to v6

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

Installation

npm install ai@latest @ai-sdk/react@latest @ai-sdk/openai@latest

Breaking changes

1. convertToModelMessages() is now async

Add await to all calls:

// v5
const result = streamText({
  messages: convertToModelMessages(this.messages),
  model: openai("gpt-4o")
});

// v6
const result = streamText({
  messages: await convertToModelMessages(this.messages),
  model: openai("gpt-4o")
});

2. CoreMessage removed

Replace CoreMessage with ModelMessage and convertToCoreMessages() with convertToModelMessages():

// v5
import { convertToCoreMessages, type CoreMessage } from "ai";

// v6
import { convertToModelMessages, type ModelMessage } from "ai";

3. Tool pattern: server-side tools (recommended)

v6 introduces needsApproval and the onToolCall callback. For most apps, define tools on the server with tool() from "ai" for full Zod type safety:

Before (v5):

// Client defined tools with AITool type
useAgentChat({
  agent,
  tools: clientTools,
  experimental_automaticToolResolution: true,
  toolsRequiringConfirmation: ["askConfirmation"]
});

After (v6):

// Server: all tools defined here
const tools = {
  getWeather: tool({
    description: "Get weather",
    inputSchema: z.object({ city: z.string() }),
    execute: async ({ city }) => fetchWeather(city)
  }),
  getLocation: tool({
    description: "Get user location",
    inputSchema: z.object({})
    // No execute -- client handles via onToolCall
  }),
  processPayment: tool({
    description: "Process payment",
    inputSchema: z.object({ amount: z.number() }),
    needsApproval: async ({ amount }) => amount > 100,
    execute: async ({ amount }) => charge(amount)
  })
};

// Client: handle tools via callbacks
useAgentChat({
  agent,
  onToolCall: async ({ toolCall, addToolOutput }) => {
    if (toolCall.toolName === "getLocation") {
      const pos = await getPosition();
      addToolOutput({
        toolCallId: toolCall.toolCallId,
        output: { lat: pos.coords.latitude, lng: pos.coords.longitude }
      });
    }
  }
});

Dynamic client tools (SDK/platform pattern):

If you are building an SDK or platform where tools are defined dynamically by the embedding application at runtime, the tools option on useAgentChat and createToolsFromClientSchemas() on the server are still fully supported:

// Server: accept whatever tools the client sends
const tools = {
  ...createToolsFromClientSchemas(options.clientTools),
  ...serverTools
};

// Client: register tools dynamically
useAgentChat({
  agent,
  tools: dynamicTools,
  onToolCall: async ({ toolCall, addToolOutput }) => {
    const tool = dynamicTools[toolCall.toolName];
    if (tool?.execute) {
      const output = await tool.execute(toolCall.input);
      addToolOutput({ toolCallId: toolCall.toolCallId, output });
    }
  }
});

4. generateObject mode option removed

Remove mode: "json" or similar from generateObject calls.

5. isToolUIPart and getToolName now include dynamic tools

In v6, these check both static and dynamic tool parts. For the old behavior, use isStaticToolUIPart and getStaticToolName. Most users do not need to change anything.

Deprecated APIs

Deprecated Replacement
toolsRequiringConfirmation needsApproval on server tools
experimental_automaticToolResolution onToolCall callback
addToolResult() addToolOutput() or addToolApprovalResponse()

Not deprecated: AITool, createToolsFromClientSchemas(), extractClientToolSchemas(), and the tools option on useAgentChat are supported for SDK/platform use cases where tools are defined dynamically at runtime.

Migration checklist

Packages:

  • ai to ^6.0.0
  • @ai-sdk/react to ^3.0.0
  • @ai-sdk/openai (and other providers) to ^3.0.0

Code changes:

  • Add await to all convertToModelMessages() calls
  • Replace CoreMessage with ModelMessage
  • Replace convertToCoreMessages() with convertToModelMessages()
  • Remove mode from generateObject calls
  • Move static tool definitions to server using tool() (recommended for most apps)
  • Use onToolCall in useAgentChat for client-side tool execution
  • Replace toolsRequiringConfirmation with needsApproval
  • Replace addToolResult() with addToolOutput() or addToolApprovalResponse()

Further reading