> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.runtype.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server. # Using prompt steps Use prompt steps to call AI models and produce text or structured data in a Flow. ## Before you begin Before you add a prompt step, check that you have the following: * A Flow open in the Flow editor. For more information, see [Creating and editing flows](/user-guide/flows/creating-and-editing-flows). * At least one enabled model in your account. For more information, see [Managing AI models](/user-guide/settings/managing-ai-models). ## Add a prompt step To add a prompt step, follow these steps: 1. In the Flow editor, click **Add step** (**+**) where you want to insert the step. 2. Select **Run Task** for a single prompt, or select **Run Agent** for a prompt that includes conversation history. 3. Configure the step with these fields: * **Name**: Enter a descriptive label, such as `Generate summary`. * **Model**: Select an AI model. * **User**: Write the prompt text. 4. Save the Flow. ## Run Task and Run Agent A **Run Task** step sends the system prompt and the user prompt to the model. A **Run Agent** step also sends conversation history. When a step runs as an agent, the prompt editor shows a **Messages** tab next to **User**. The editor fills it with `{{messages}}`, the conversation history that the Flow receives. You can replace it with a literal message array or another variable. For more information, see [Message variables](/user-guide/flows/flow-variables-and-templates#message-variables). To change the mode after you add the step, open the step's action menu (**⋯**) and choose **Switch to Task** or **Switch to Agent**. Switching to Task removes the conversation history from the step. For help choosing between a Flow and an Agent, see [Choosing between a flow and an agent](/user-guide/flows/choosing-between-a-flow-and-an-agent). ## Write prompts Write a specific instruction that names the task, required format, and important constraints. A vague prompt leaves the output format open: **`Vague prompt`** ```plaintext title="Vague prompt" Summarize this. ``` A specific prompt defines the required length and focus: **`Specific prompt`** ```plaintext title="Specific prompt" Summarize the following customer email in 2 to 3 sentences. Focus on the main request and any urgency indicators. Email: {{EMAIL_TEXT}} ``` Replace `EMAIL_TEXT` with the Flow input that contains the customer email. When the output format matters, include a representative input and output in the prompt. Include only the context that the model needs for the task, because extra context adds tokens and can pull the response off topic. To get suggested improvements to a prompt, click **Optimize prompt** in the prompt editor, and then describe what you want to improve. ## Use template variables Use template variables in prompts to reference Flow inputs and outputs from previous steps: **`Prompt with template variables`** ```plaintext title="Prompt with template variables" You are a customer support agent for {{COMPANY}}. Customer message: {{CUSTOMER_MESSAGE}} Customer tier: {{CUSTOMER_TIER}} Previous interactions: {{PREVIOUS_INTERACTION_COUNT}} Provide a helpful, professional response. ``` Replace `COMPANY`, `CUSTOMER_MESSAGE`, `CUSTOMER_TIER`, and `PREVIOUS_INTERACTION_COUNT` with the corresponding Flow input or step output names. Flow input names are the keys that you pass in the `inputs` field of a run request. Step output names are the values in each step's output variable field. ## Choose a model Use a routed model ID such as `claude-sonnet-5`, `gpt-5.6-terra`, or `gemini-3.8-flash`. Runtype routes these IDs to supported providers without a provider-specific version in your Flow. Choose a model based on task complexity, response time, and cost. For the full list, see [Available AI models](/user-guide/settings/available-ai-models). ## Configure parameters Use **Advanced Settings** to adjust model behavior. ### Temperature Turn off **Use model default**, then set **Temperature** from `0` to `1` with the slider. Lower values reduce variation, and higher values increase variation. Through the API, `temperature` accepts values from `0` to `2`. Runtype omits **Temperature** for models that reject the parameter. Claude 5 models and some GPT-5 models reject it. Use **Top P** to control variation when a model does not support **Temperature**. ### Max output tokens Set **Max output tokens** to limit the response length. Leave it on **Use model default** when you do not need a custom limit. ### System prompt Use the **System** editor for role definitions and instructions that apply across the prompt. ### Advanced sampling parameters The editor shows provider-supported sampling parameters. The following table describes their ranges and effects: | Parameter | Range | Description | | ------------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------- | | **Top P** (`topP`) | `0` to `1` | Limits token selection to the most probable tokens whose combined probability reaches this value. Lower values focus the selection. | | **Top K** (`topK`) | `1` to `500` | Limits token selection to the `K` most probable tokens at each step. | | **Frequency Penalty** (`frequencyPenalty`) | `-2` to `2` | Positive values reduce repeated tokens. | | **Presence Penalty** (`presencePenalty`) | `-2` to `2` | Positive values increase the likelihood of new topics. | | **Seed** (`seed`) | Integer | Requests repeatable output when the provider supports it. | Not every provider supports every parameter. The editor shows the parameters supported by the selected model's provider. Leave a parameter on **Use model default** to use the provider's default value. ### Reasoning To use reasoning, select a model that supports it. The editor then shows **Reasoning** and the controls that model accepts. Select **Enable reasoning** to allocate part of the model call to reasoning. The editor offers only the effort levels and budget range that the selected model accepts. The following table lists the controls by provider: | Provider | Control | Values | | --------------------------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | OpenAI | **Reasoning effort** | The levels the selected model publishes, drawn from `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. | | OpenAI | **Reasoning summary** | **Auto (condensed)** or **Detailed** (`auto` or `detailed` in the API). **Auto (condensed)** is required for streaming reasoning output. | | Anthropic (Claude 4.5 and earlier) | **Thinking budget (tokens)** | A token budget for extended thinking, within the range the model publishes. Most Claude models set a minimum of 1024 tokens. | | Anthropic (Claude 4.6 and later, and the Claude 5 family) | **Reasoning effort** | The levels the model publishes, such as `low`, `medium`, `high`, `xhigh`, and `max`. | | Google (Gemini 2.5) | **Thinking budget (tokens)** | A token budget, within the range the model publishes. | | Google (Gemini 3 and later) | **Thinking level** | The levels the model publishes, drawn from `minimal`, `low`, `medium`, and `high`. | | xAI | **Reasoning effort** | The levels the model publishes, such as `low`, `medium`, and `high`. | Two models from the same provider can offer different levels. `gpt-5.6-luna` offers **Low**, **Medium**, **High**, **Extra high**, and **Max**, and does not offer **Minimal**, while `gpt-5-mini` does offer **Minimal**. A model served from a custom inference endpoint shows **Reasoning effort** only after it is declared as a reasoning model on its model configuration, and offers `low`, `medium`, and `high`. Runtype sends the chosen value as `reasoning_effort` (or `reasoning.effort` on the Responses format) without checking it against the endpoint. For the declaration and how the value on the wire is chosen, see [Reasoning models on custom inference endpoints](/user-guide/integrations/connecting-ai-model-providers#reasoning-models-on-custom-inference-endpoints). Claude 4.6 and later, and the Claude 5 family, use adaptive thinking. Adaptive thinking carries no token budget, so the editor shows **Reasoning effort** for those models and no budget input. If a step still carries a `budgetTokens` value from an earlier model choice, Runtype drops it before it sends the request and validation reports `REASONING_KNOB_UNSUPPORTED`. For more information, see [Flow validation warnings](/user-guide/flows/flow-validation-warnings). Some models always reason. On those, turning reasoning off selects the model's lowest effort level instead of disabling reasoning, and the editor says so under the **Disable reasoning** option. If a step carries an effort level the selected model does not publish, the editor keeps the saved value in the list and marks it as one the model does not accept. Pick another level to replace it. Higher effort and larger budgets use more tokens and can increase response time. For short extraction or classification tasks, leave reasoning off. ## Access output Enter a name in each prompt step's output variable field. Reference that variable in later steps with this syntax: **`Step output`** ```plaintext title="Step output" {{SUMMARY_RESULT}} ``` Replace `SUMMARY_RESULT` with the step's output variable name. Use the output variable name, not the step name, in every reference. ### Choose a response format To set the output format, open **Advanced Settings**, turn off **Use model default** under **Response Format**, and select a format. The following formats are available: * **Markdown**: Asks the model to respond in Markdown, for display in a chat or document. * **JSON**: Asks the model to respond in JSON, so that later steps can read the result field by field. * **HTML**: Asks the model to respond in HTML, for pages or email bodies. * **XML**: Asks the model to respond in XML, for systems that expect XML. Leave **Use model default** on to send no format instruction to the model. When **Response Format** is **JSON** (`responseFormat: json`), access properties in the returned object with dot notation: **`Nested JSON output`** ```plaintext title="Nested JSON output" {{EXTRACT_DATA.customerName}} {{EXTRACT_DATA.orderAmount}} ``` Replace `EXTRACT_DATA` with the step's output variable name. Use property names that the JSON response returns. To read a fixed set of typed values, such as an order ID, a date, and an amount, use an [Extract Fields step](/user-guide/flows/extraction) instead. It returns each field as a value of its type or `null`, with a confidence. **JSON** does not validate the response against a schema, so describe the exact keys and value types in the prompt. Runtype removes code fences from the response and extracts the JSON object. If the response is not valid JSON, the variable holds the raw text, and dot-notation references stay unresolved as literal template text. ### Show or hide the output Each prompt step card has an output visibility drop-down in its output row. Choose one of these options: * **Stream to user**: Show the step's output to the user in real time. This is the default. * **Store result only**: Save the output to the variable without showing it to the user. Use **Store result only** for intermediate steps, such as extraction or classification, whose output only later steps use. This keeps that text out of the chat or API response stream. ## Test a prompt step To test a top-level prompt step against the variables from the last run, follow these steps: 1. Run the Flow once. 2. On the step card, open the action menu (**⋯**). 3. Choose **Test with last run**. The test sheet opens. 4. Review the output, and update the prompt if needed. To compare prompts and models across many inputs, use Evals. For more information, see [Running an eval](/user-guide/evals/running-an-eval). ## Handle errors Prompt steps can fail when an API quota is exhausted, a model rate limit is reached, or an API key is invalid. A prompt can also exceed the model context. **Run Task** and **Run Agent** steps continue to the next step after an error. Their error-handling setting controls only whether the fallback chain runs, not whether the Flow stops. As a result, **Continue on error** and **Stop on error** act the same way for prompt steps, although the editor describes **Stop on error** as stopping the Flow. Two failures stop the Flow whatever the setting: * Your platform credit is exhausted. * A required saved MCP connection is unavailable. This failure skips all fallbacks, including fixed messages. To run fallbacks after an error, click the error-handling control on the step card and select **Use fallbacks**. ### Configure fallbacks A fallback chain runs each fallback in order until one succeeds. Each fallback has one of these types: * **Retry**: Run the same model again. * **Different model**: Switch to a backup model. You can set **Temp** to override the temperature. Through the API, you can also override `maxTokens`. * **Fixed message**: Return a pre-written reply without calling a model. Use this as the last fallback when you want an author-written response after model fallbacks fail. **Retry** and **Different model** fallbacks also have a **Delay** field, in milliseconds. Runtype waits at least that long before it runs the fallback. After a rate-limit error, set a delay on **Retry** so that the provider has time to accept requests again. If a rate-limited provider says how long to back off (a `Retry-After` header or a rate-limit reset time) and that is longer than the **Delay**, a **Retry** fallback waits for the provider's time instead, up to 60 seconds. Runtype skips that wait and moves on to the next fallback when a **Different model** fallback comes later in the list, or when the wait would run past the flow's timeout. Stopping the run cancels the wait. A fallback never runs a tool twice. If the failed attempt already called a tool, Runtype skips the **Retry** and **Different model** fallbacks and moves to the next fallback, so a **Fixed message** still applies. If no fallback remains, the step fails with the original error. Tools marked `idempotent` do not count as a tool call here. Choose when to run the fallback chain: * **The step errors**: Run fallbacks when a provider error, timeout, or thrown failure occurs. * **The reply is empty**: Run fallbacks when the model finishes without visible text. You can enable both triggers. A provider can return a refusal without a transport error. When **The step errors** is enabled, that refusal triggers the fallback chain. **Retry** is skipped for a refusal because it calls the same model and configuration. Use **Different model** or **Fixed message** when you need a different response after a refusal. If a fallback returns a refusal, the chain advances to the next fallback. Add **Fixed message** last when you want a non-model response after other fallbacks fail. ### Stop a Flow after a prompt failure To stop a Flow when a prompt step fails, follow these steps: 1. After the prompt step, add a **Conditional Logic** step. 2. In the condition, check whether the prompt step's output variable is empty. 3. Route the empty branch to a stop or error path. ## Add tools to a prompt step To let the model call tools, follow these steps: 1. On the step card, click the tools field. It shows **No tools** until you add one. The tools panel opens. 2. Select the tools that the model can call. To narrow the list, filter by a category, such as **Web search** or **Records**, or by a source, such as **MCP servers**, **Custom tools**, or **Semantic search**. 3. Optional: To change **Tool call strategy**, click **Settings** in the tools panel. For more information, see [Tool call strategy](#tool-call-strategy). 4. Click **Save**. To let the model stream Markdown or a component as an artifact to clients that support artifacts, select **Emit Artifact (Markdown)** or **Emit Artifact (Component)** under the **Artifacts** category. For more information about tools, see [Built-in tools](/user-guide/tools/built-in-tools) and [Creating custom tools](/user-guide/tools/creating-custom-tools). ## Tool call strategy Set **Tool call strategy** in the tools panel's **Settings** view to control whether the model calls a tool. The following table describes each strategy: | Strategy | Behavior | | ---------------------- | -------------------------------------------------------- | | **Auto (recommended)** | The model chooses whether to call a tool or return text. | | **Required** | The model must call a tool for the turn. | | **None** | The step does not offer tools to the model. | Use **Auto** for most prompt steps. Use **Required** only to force exactly one tool call, and set the step's `tools.maxToolCalls` to `1`. The Flow editor has no control for this limit, so set it through the API or in a Flow definition that you manage as code. If `maxToolCalls` is unset or higher than `1`, the step can return empty output because the model stays in tool-call mode. The **Settings** view shows a warning when **Required** is selected without that limit. ## Next steps Use these pages to continue working with prompt steps: * [Flow variables and templates](/user-guide/flows/flow-variables-and-templates): pass data between steps * [Using transform-data steps](/user-guide/flows/using-transform-data-steps): process prompt output * [Debugging flows](/user-guide/flows/debugging-flows): find out why a prompt step failed or returned empty output * [Manage flows as code](/user-guide/flows/manage-flows-as-code): set step fields that the editor does not show * [Prompt caching](/user-guide/settings/prompt-caching): reduce cost and latency for repeated system prompts