Prompts and Messages

Purpose and Scope

Prompts are the application-facing instructions and conversation data that AI SDK Core sends to a language model. The repository documentation frames prompting as a simplification layer over provider-specific prompt interfaces: developers should be able to express a simple string, a persistent set of system instructions, or a chat-style message history without learning each provider’s native wire format first. This page explains those supported prompt shapes, how they are standardized before a model call, and where multimodal file-like content fits into the same model-message pipeline.

Sources: content/docs/02-foundations/03-prompts.mdx, packages/ai/src/prompt/standardize-prompt.test.ts

The most important distinction is between user-supplied prompt content and trusted application instructions. A text prompt is the smallest useful shape: one string supplied through the prompt property to APIs such as generateText and streamText. A system prompt is not another user message; it is application-controlled guidance supplied through the instructions property. Message prompts are arrays of role-tagged entries and are the normal representation for chat history, assistant turns, tool results, and multimodal requests.

Sources: content/docs/02-foundations/03-prompts.mdx

Relevant Source Files

• content/docs/02-foundations/03-prompts.mdx - First-party foundations documentation for text prompts, system instructions, message prompts, role/content structure, provider options, and the warning about model capability differences.
• packages/ai/src/prompt/standardize-prompt.test.ts - Test coverage for prompt normalization rules, including rejected system messages, empty message arrays, allowed system-message opt-in, and instructions handling.
• packages/ai/src/prompt/convert-to-language-model-prompt.test.ts - Test coverage for the conversion step that prepares standardized prompt data for the language-model-facing representation.
• packages/ai/src/prompt/file-part-data.test.ts - Test coverage for file part normalization, including inline data, URLs, data URLs, provider references, and tagged file data shapes.

Core Prompt Shapes

Use a text prompt when the call is a single-turn generation task. The docs describe text prompts as strings that are ideal for simple generation use cases, including repeated generation from a prompt template. Dynamic data can be interpolated with ordinary TypeScript template literals before the AI SDK call. In the standardized prompt result, this simple string becomes a user message, which keeps downstream model invocation code working with a consistent message-oriented shape even when the caller used the shorter prompt property.

Sources: content/docs/02-foundations/03-prompts.mdx, packages/ai/src/prompt/standardize-prompt.test.ts

const result = await generateText({
  model,
  prompt: 'Invent a new holiday and describe its traditions.',
});

Use system instructions when the application needs to guide behavior across the request. The docs call these the initial instructions that constrain model behavior, and the public property is instructions. They work alongside both prompt and messages, so a route handler can keep policy, formatting, or task definition in one place while passing a user request or chat history separately. The tests show that instructions may be a system model message and may also be an array of system model messages, preserving a structured representation rather than forcing all instructions into one string.

Sources: content/docs/02-foundations/03-prompts.mdx, packages/ai/src/prompt/standardize-prompt.test.ts

const result = await generateText({
  model,
  instructions:
    'You help plan travel itineraries. Respond with the best stops to make.',
  prompt: `I am planning a trip to ${destination} for ${lengthOfStay} days.`,
});

Use message prompts for chat and richer interactions. A message prompt is an array of user, assistant, and tool messages; each message has a role and a content field. The documentation emphasizes that content can be plain text for user and assistant messages, or an array of content parts for the relevant message type. That lets the same messages property carry ordinary chat history, tool-related turns, and multimodal parts when the selected model supports them.

Sources: content/docs/02-foundations/03-prompts.mdx

const result = await generateText({
  model,
  messages: [
    { role: 'user', content: 'Hi!' },
    { role: 'assistant', content: 'Hello, how can I help?' },
    { role: 'user', content: 'Where can I buy Currywurst in Berlin?' },
  ],
});

Standardization and Safety Rules

Prompt standardization is the boundary that turns flexible public input into a predictable internal shape. The standardizePrompt tests show that a string prompt is normalized into a user message, while instructions remain separate from the messages array. The same tests also show several validation failures that matter in application code: an empty messages array is invalid, and system messages embedded directly in either messages or prompt-message arrays are rejected by default with InvalidPromptError. These behaviors keep callers from accidentally sending ambiguous or unsafe histories.

Sources: packages/ai/src/prompt/standardize-prompt.test.ts

The system-message rule is intentionally security-sensitive. The docs warn that system messages in prompt or messages are rejected by default and recommend using instructions for system instructions. There is an opt-in flag, allowSystemInMessages, for cases where a trusted server has to forward an existing history that already contains system messages. When that flag is set, tests show the system message is preserved, but a system message with part-array content is still rejected. Treat this opt-in as a compatibility escape hatch, not the normal way to accept user-provided chat histories.

Sources: content/docs/02-foundations/03-prompts.mdx, packages/ai/src/prompt/standardize-prompt.test.ts

After standardization, prompt data is converted for the language model implementation selected by the model option. The repository keeps this conversion behavior under prompt-focused tests, including convert-to-language-model-prompt.test.ts, which marks the boundary between SDK-facing prompt, instructions, and messages options and the provider-facing language model prompt representation. As a user of the public API, the practical takeaway is that you should express intent in the documented prompt shapes and let AI SDK Core adapt that shape to the provider package and model capability layer.

Sources: packages/ai/src/prompt/convert-to-language-model-prompt.test.ts, content/docs/02-foundations/03-prompts.mdx

Multimodal and File Parts

Message content can be an array of parts, which is how text can be combined with other data in a single user turn. The docs caution that not every model supports every message or content type, so multimodal prompts should be paired with an explicit provider and model choice that advertises the needed capability. This is especially important for file, image, or document-like inputs: the prompt shape may be valid in the SDK, but the selected language model may still reject or ignore unsupported content.

Sources: content/docs/02-foundations/03-prompts.mdx

File part normalization makes those richer content parts less fragile for callers. The convertToLanguageModelV4FilePart tests show support for legacy bare shapes such as Uint8Array, ArrayBuffer, base64 strings, URL strings, URL instances, data URLs, and provider references. They also show tagged shapes such as { type: 'data', data }. The conversion result distinguishes inline data, URLs, and provider references, and it extracts a media type from a data URL while preserving the underlying base64 payload as data.

Sources: packages/ai/src/prompt/file-part-data.test.ts

There is one subtle but useful distinction in the file part tests: a bare data URL can be parsed into data plus media type, but a tagged { type: 'data', data: 'data:...' } value is rejected because a data URL is not considered inline data in that tagged position. This prevents a value that looks explicitly pre-normalized from hiding another encoding layer. When building multimodal message content, prefer clear part shapes and include media type information where the input format supplies it.

Sources: packages/ai/src/prompt/file-part-data.test.ts

Compact Reference

Sources: content/docs/02-foundations/03-prompts.mdx, packages/ai/src/prompt/standardize-prompt.test.ts, packages/ai/src/prompt/file-part-data.test.ts

Practical Guidance and Next Steps

Start with the narrowest prompt shape that describes the task. If there is no conversation history, use prompt; if the application needs durable behavioral guidance, add instructions; if the request comes from a chatbot, pass messages. Keep system instructions server-controlled, and do not enable allowSystemInMessages for histories assembled directly from untrusted users. For multimodal prompts, validate both the content shape and the selected model’s capabilities, because the SDK can standardize message parts without guaranteeing that every provider model accepts them.

Sources: content/docs/02-foundations/03-prompts.mdx, packages/ai/src/prompt/standardize-prompt.test.ts

Read Providers and Models next to choose models with the right content capabilities, then Tools Foundations if your message history includes tool calls or tool results. If you are building a UI chatbot, continue to the UI pages that explain converting UI messages into model messages; the official API uses convertToModelMessages to transform useChat message state into ModelMessage objects compatible with core functions such as streamText. That UI conversion step complements the core prompt standardization described here rather than replacing it.