# Write a prompt in Compose

Build a prompt from message blocks in Compose, declare and use variables, pick the model and its parameters, define an output schema, and save.

**Compose** is the prompt itself: an ordered list of message blocks on the left and an inspector on the right. Edits autosave a few seconds after you stop typing, and are flushed when you leave the tab; on a live version they are not autosaved and **Save** makes a new draft version instead.

**Who can use it:** the **Builder** role or higher. A prompt shared with you that you may not edit opens read-only with a banner telling you to ask the owner.

## Message blocks

![Prompt Studio on the Compose tab: a Prompts rail listing Support Reply Drafter, Sales Forecast Narrator and SQL Explainer, an approval banner, the title Support Reply Drafter with v3 · live and LIVE IN 1 AGENT, the buttons Suggest, Compare models, Save and Run, and the tabs Compose, Test, Profile, Evals, Deployments and History.](https://docs.katonic.ai/img/agents/prompt-studio/prompt-studio-compose.png)
*Prompt Studio: the prompt library on the left, the editor header with the version and the agents the prompt is live in, and the message blocks of the prompt itself.*

Each block carries a role and a body. **System** is behaviour and guardrails, **User** is the customer's message and is where variables are substituted at runtime, and **Assistant** is a response template or a few-shot example. The footer of each block estimates its tokens and counts the variables it uses.

A block's own controls copy it, delete it, and open a menu to duplicate it, move it up or down, or change its role. The row beneath the blocks adds a **System**, **User** or **Assistant** block, or a **Few-shot pair**, which inserts a user and assistant block together; a few-shot pair offers **+ Add example** to add another. **Tool spec** is dimmed, because tool specifications belong to the agent.

Two banners can appear above the blocks. A prompt whose current version is live warns that edits create a new draft version and that live agents are unaffected until you promote. While a model is generating, a banner offers to cancel, and a model that times out offers to retry.

## Variables

![The inspector on the Variables tab listing the prompt's variables with their types and an auto or runtime tag, a Declare link and a legend distinguishing auto-detected from runtime variables.](https://docs.katonic.ai/img/agents/prompt-studio-compose/prompt-studio-variables.png)
*The Variables inspector: each placeholder with its type, whether it was auto-detected from the prompt body or is supplied at runtime, and Declare for one defined up front.*

Writing `{{name}}` in a message body declares a variable by use; the inspector's **Variables** tab lists it as auto-detected. **+ Declare** adds one up front with a type (text, number, boolean, a constrained list of values, or conversation history), an optional default and a description; declaring one inserts its placeholder into the last user message if it is not already there.

Each row shows the placeholder, its type and whether it was auto-detected or is supplied at runtime. A variable with a fixed list of values lets you choose which one test runs use. An auto-detected variable cannot be deleted from the list: remove it from the prompt body instead.

**Tags** below accept lowercase words; Enter or a comma commits one. **Used by** lists the agents and workflows that reference this prompt, with the version each pins. It is read-only, because a dependency is removed in the agent's builder.

## Model and parameters

![The inspector on the Model tab showing the selected model with its provider and tier, badges for Tier and Context, and sliders for Temperature, Top-p and Max output under Tune parameters.](https://docs.katonic.ai/img/agents/prompt-studio-compose/prompt-studio-model.png)
*The Model inspector: the model this prompt runs on, its tier and context window, and the prompt's default temperature, top-p and maximum output.*

The **Model** tab picks the model this prompt runs on, from the models the AI Gateway offers. The card shows its provider and tier, and beside it the tier and context window the gateway reports.

**Tune parameters** sets the prompt's defaults: **Temperature**, **Top-p** and **Max output**. These are defaults, not a contract. An Optimizer run may vary them per candidate, and a deployed agent inherits them unless its own configuration overrides them. Where the gateway publishes prices, the footer gives the cost per thousand input and output tokens.

## Output schema

![The inspector on the Schema tab with a JSON editing box and an explanation of what the schema is used for.](https://docs.katonic.ai/img/agents/prompt-studio-compose/prompt-studio-schema.png)
*The Schema inspector: the JSON shape the output must match, used by the schema evaluator and to validate responses at runtime.*

The **Schema** tab defines the JSON shape the prompt's output must match, used by the schema evaluator and to validate responses at runtime. Valid JSON is accepted and reformatted; invalid JSON is reported and not kept, so the last valid schema survives a typo. Like everything else here, it is stored when you save.

## Verify

Select **Save**. The header's version rises, and the change appears in [History](/agents/prompt-studio-versions).

## Troubleshooting

- **Couldn't save prompt.** The save was refused. If the message says the prompt was updated by someone else, reload and reapply your change rather than overwriting theirs.
- **Invalid JSON, not saved.** The schema box holds text that is not JSON. The previous schema is still in place.
- **No model set.** Pick one on the Model tab, or test runs refuse to start and say so.

## Related

- [Prompt Studio](/agents/prompt-studio)
- [Test a prompt against cases](/agents/prompt-studio-test)
- [Compare, suggest and share](/agents/prompt-studio-compare-and-share)

Source: https://docs.katonic.ai/agents/prompt-studio-compose
