Settings, Reasoning, and Prompt Engineering

Purpose and Scope

This page connects three decisions that usually happen together when calling an AI SDK language model: how to write the prompt, how to tune common model settings, and how to decide whether reasoning should be enabled or exposed. A prompt is the instruction payload sent to the model. Settings are call options such as output limits, temperature, retries, and timeouts that influence generation behavior. Reasoning is a portable AI SDK control for models that perform an internal thinking phase before producing a final answer.

The repository source for this page is the foundations prompt guide, which defines the AI SDK prompt model in reader-facing terms. It explains that providers often expose complex prompt interfaces, while the AI SDK simplifies prompting into text prompts, system instructions, and message prompts. That same separation is the key to safe call tuning: keep durable behavior in instructions, put user work in prompt or messages, and reserve provider-specific or model-behavior controls for settings and provider options.

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

Relevant Source Files

• content/docs/02-foundations/03-prompts.mdx - Defines AI SDK prompt terminology, including text prompts, system prompts through instructions, message prompts through messages, multimodal message parts, provider options, and the warning around allowSystemInMessages.

Core Primitives

The simplest prompt primitive is a text prompt. In AI SDK calls such as generateText and streamText, the prompt property accepts a string and is intended for simple generation tasks or reusable prompt templates. The prompt guide explicitly shows static text and template literals, which makes text prompts a good fit for tasks like content variants, summarization, and small server-side utilities where the application assembles all necessary context before the call.

System prompts are represented with the instructions property. The source documentation describes these as the initial instructions that guide and constrain model behavior, and it states that they work with both text prompts and message prompts. That distinction matters for prompt engineering because system instructions should normally come from trusted server-side code, while user prompts and message histories can include untrusted content supplied by the user or client.

Message prompts are arrays of messages with a role and content. The documented roles include user, assistant, and tool messages, which makes the message format the natural representation for chat interfaces, prior assistant turns, tool results, and more complex workflows. Message content can be plain text for user and assistant messages, or an array of parts for richer inputs. The source also warns that not every model supports every message or content type, so model capability should be considered before relying on multimodal or tool-message inputs.

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

Prompt Engineering Workflow

Start by choosing the narrowest prompt shape that represents the task. If the request is a single instruction with dynamic variables, use prompt. If the request includes durable behavior such as tone, role, domain boundaries, or response format expectations, put that behavior in instructions and keep the changing user request in prompt. If the interaction depends on conversation history, assistant turns, tool messages, or multimodal parts, use messages so the role structure is explicit rather than embedded into one long string.

The most important safety boundary is system instruction handling. The prompt guide says that system messages inside prompt or messages are rejected by default and that instructions should be used for system instructions. It also documents allowSystemInMessages: true for cases where existing message histories contain system messages, while warning that opting in can create prompt injection risk because users may override or set system behavior by injecting system messages. In practice, only trusted server code should author system instructions.

A practical prompt iteration loop is to first write the task in plain language, then separate durable policy from user-provided input, and finally add structure only where it improves reliability. For example, travel-planning behavior belongs in instructions, while destination and trip length belong in the user prompt. Chat history belongs in messages, not in a manually concatenated transcript, because roles help the SDK and providers preserve intent across turns.

const result = await generateText({
  model: model,
  instructions:
    'You help planning travel itineraries. ' +
    'Respond with a concise list of the best stops.',
  prompt:
    `I am planning a trip to ${destination} for ${lengthOfStay} days. ` +
    'Please suggest tourist activities.',
});

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

Settings and Reasoning Controls

AI SDK Core settings complement prompt design by controlling the generation call without changing the wording of the prompt. The official settings documentation describes common settings available in addition to the model and prompt, including examples such as maxOutputTokens, temperature, maxRetries, and timeout. Treat these as operational and sampling controls: they shape how much the model can produce, how deterministic the response should be, how long the call may run, and how the SDK should handle transient failures.

Settings are not a substitute for clear instructions. If the model should answer as a travel planner, that belongs in instructions; if the model should produce at most a bounded answer, use maxOutputTokens; if the answer should be less exploratory, lower temperature. The official settings guidance also notes that some providers do not support every common setting and that unsupported settings can produce warnings on the result object. That means robust code should inspect warnings when using portable settings across multiple providers.

Reasoning controls apply to models that support an internal reasoning or thinking phase. The official reasoning guide describes a top-level reasoning parameter for generateText and streamText, with values such as provider default behavior, disabling reasoning, or selecting a reasoning intensity. Reasoning should be viewed as a model behavior option rather than prompt text. Use it when the task benefits from deliberate planning, estimation, or multi-step analysis, and keep prompt wording focused on the user-visible task and output requirements.

Reasoning output also affects product behavior. The official reasoning guide shows calls returning text, reasoning, and reasoningText, which means an application may receive both the final answer and structured or textual reasoning artifacts when supported. Decide deliberately whether to store, display, redact, or ignore those artifacts. For many user interfaces, the final answer is the stable product surface, while reasoning metadata is better suited for debugging, evaluation, or internal traces.

Provider Options and Message-Level Tuning

Provider options are the escape hatch for provider-specific behavior. The supplied docs explain that functions such as generateText and streamText accept providerOptions at the function-call level, and message objects can also carry provider options for more granular control. This matters when a provider exposes features that are not part of the common settings surface, such as provider-specific reasoning effort, caching behavior, or other metadata that should only apply to a particular provider or message.

Use provider options sparingly and close to the reason they are needed. A function-level provider option is appropriate when the whole call should opt into a provider feature. A message-level provider option is better when a capability applies to one instruction or message, such as caching a trusted system instruction. This keeps portable prompt structure intact while still allowing advanced provider features. The prompt source places provider options inside the prompt discussion, which reinforces that options can be part of prompt delivery without becoming prompt content.

Compact Reference

Next Steps

When tuning a call, make one change at a time: first clarify instructions, then choose the right prompt shape, then set common settings, and only then add reasoning or provider-specific options. If a prompt history includes system messages, audit whether those messages are trusted before enabling allowSystemInMessages. For deeper implementation work, continue with the pages on providers and models, provider options, generating text and streaming, and runtime and tool context.

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