Core function message input
Constructing prompts for generateText or streamText
AI Tools · Type Alias
CoreMessage
CoreMessage is the union used to describe system, user, assistant, and tool messages for AI SDK Core functions. Its role determines the allowed content structure, including multimodal user content and tool results.
How it works
CoreMessage is the union of message shapes accepted by AI SDK Core operations. Each value identifies its role and carries role-specific content, allowing prompts to represent system instructions, user input, assistant output, or tool results.
Syntax
type CoreMessage = CoreSystemMessage | CoreUserMessage | CoreAssistantMessage | CoreToolMessage;Parameters
| Name | Type | Description |
|---|---|---|
CoreMessage | CoreSystemMessage | CoreUserMessage | CoreAssistantMessage | CoreToolMessage | An ordered conversation message with one of the documented system, user, assistant, or tool roles. |
Returns
A discriminated union type for AI SDK Core conversation messages.
Key points
- CoreMessage is intended for the messages input accepted by AI SDK Core functions.
- Use coreMessageSchema when runtime validation of CoreMessage values is needed.
- CoreSystemMessage uses role 'system' with string content for instructions or context.
- CoreUserMessage supports plain text or multimodal content made from text, image, and file parts.
- CoreAssistantMessage can record the model's textual response and tool-call content together.
- CoreToolMessage carries tool results as tool content, enabling tool responses in the conversation.
Common mistakes
- Use CoreMessage for AI SDK Core message inputs; UI message types are a different representation.
- Do not add the old conversion step when passing messages from current UI APIs unless the relevant API specifically requires it.
Example: Passing CoreMessage values to generateText
import { generateText, type CoreMessage } from 'ai';
import { openai } from '@ai-sdk/openai';
const messages: CoreMessage[] = [
{ role: 'system', content: 'Answer concisely.' },
{ role: 'user', content: 'What is 2 + 2?' },
];
const { text } = await generateText({
model: openai('gpt-4o-mini'),
messages,
});
console.log(text);The message array is explicitly typed as CoreMessage[] and passed to a core text-generation function.
When to use it
Multimodal user conversations
Representing image or file prompts
Tool-enabled exchanges
Preserving model tool calls and their results
Interview questions
QWhat is CoreMessage?
CoreMessage is a union of role-specific message types: system, user, assistant, and tool. The role determines the content shape and meaning.
Follow-up: How would you represent an image prompt? Use a user message whose content is a UserContent array containing the appropriate image part alongside any text part.
QHow do system and user messages differ?
A system message has role 'system' and string content, while a user message has role 'user' and UserContent. UserContent may be plain text or an array containing text, image, and file parts.
Follow-up: Why use structured parts instead of one string? Structured parts allow multimodal prompts while preserving the type and data of each content element.
QHow are tool interactions represented?
A tool message has role 'tool' and ToolContent, represented as an array of tool-result parts. An assistant message can contain generated text, tool calls, or both.
Follow-up: What should be validated before sending these values? Validate the role-specific structure with the exported coreMessageSchema when runtime input is not trusted.
Related
CoreSystemMessageCoreUserMessageCoreAssistantMessageCoreToolMessagecoreMessageSchemaTextPartImagePartFilePart