toAISdkMessages()

Converts messages from input formats to AI SDK UI message format. toAISdkMessages() keeps the existing AI SDK v5/default behavior. If your app is typed against AI SDK v6, pass version: 'v6'.

version: 'v6' uses the MessageList AI SDK v6 UI output path. MessageList input detection and ingestion remain unchanged.

Usage example

app/chat/page.tsx

import { toAISdkMessages } from '@mastra/ai-sdk/ui'
import { useChat } from 'ai/react'

// Stored messages from your database, memory, or API
const storedMessages = [
  { id: '1', role: 'user', content: 'Hello', parts: [{ type: 'text', text: 'Hello' }] },
  {
    id: '2',
    role: 'assistant',
    content: 'Hi there!',
    parts: [{ type: 'text', text: 'Hi there!' }],
  },
]

export default function Chat() {
  const { messages } = useChat({
    initialMessages: toAISdkMessages(storedMessages, { version: 'v6' }),
  })

  return (
    <div>
      {messages.map(message => (
        <div key={message.id}>
          {message.role}: {message.parts.map(part => (part.type === 'text' ? part.text : null))}
        </div>
      ))}
    </div>
  )
}

Parameters

messages:

MessageListInput

Messages to convert. Can be a string, array of strings, a single message object, or an array of message objects in any supported format.

options.version?:

'v5' | 'v6' | 'v7'

Selects the AI SDK message type to return. Omit it or pass 'v5' for the existing default behavior. Pass 'v6' when your app is typed against AI SDK v6 useChat() message types. Pass 'v7' when your app is typed against AI SDK v7.

Returns

Returns an array of AI SDK UIMessage objects typed for the selected version.

id:

string

Unique message identifier.

role:

'user' | 'assistant' | 'system'

The role of the message sender.

parts:

UIMessagePart[]

Array of UI parts including text, tool results, files, reasoning, sources, and step markers.

metadata?:

Record<string, unknown>

Optional metadata including createdAt, threadId, resourceId, and custom fields.

Terminal error parts

When a v2 agent reaches a terminal failure, Mastra stores the failed assistant turn with an error part. The stored payload contains only the error name and message:

const terminalErrorPart = {
  type: 'error',
  error: {
    name: 'Error',
    message: 'The model request failed.',
  },
}

toAISdkMessages() preserves this part in AI SDK UI messages so your application can render failed turns from history. Mastra removes error parts when it converts messages into provider prompts. An assistant message containing only an error part is omitted from the next model request.

Examples

Using the default AI SDK v5 types

import { toAISdkMessages } from '@mastra/ai-sdk/ui'

const messages = toAISdkMessages(['Hello', 'How can I help you today?'])

Returning AI SDK v6 message types

import { toAISdkMessages } from '@mastra/ai-sdk/ui'

const messages = toAISdkMessages(['Hello', 'How can I help you today?'], {
  version: 'v6',
})

Loading messages with Mastra client

import { MastraClient } from '@mastra/client-js'
import { toAISdkMessages } from '@mastra/ai-sdk/ui'

const client = new MastraClient()

const { messages } = await client.listThreadMessages('thread-id', { agentId: 'myAgent' })
const uiMessages = toAISdkMessages(messages)

Related

• toAISdkStream()
• toAISdkV5Messages()
• toAISdkV4Messages()