Prompts

Prompt blocks are reusable instruction templates that you compose into an agent's system prompt. Each block can contain plain text, template variables, and display conditions. Non-technical team members can edit prompt content, test different phrasings, and publish changes. Every edit is versioned, so you can compare prompt variations, roll back, and track what changed over time. You can create and manage prompt blocks through the Studio UI or programmatically through the server API, then reference them across multiple agents.

Quickstart

1. Go to the Prompts tab in Studio.
2. Select Create prompt and enter a name and your instruction text.
3. Save the prompt block and publish it.
4. Open an agent's Instructions section and select Add block.
5. Pick the saved prompt block from the block picker dialog.

The block appears as a reference in the agent's instruction list. Changes to the original prompt block update every agent that references it.

Block types

An agent's instructions are made up of an ordered list of blocks. Each block is one of three types:

Type	Description
Inline text	Free-form text written directly in the agent's instruction list. Lives only on that agent.
Prompt block	A standalone block with its own content, stored in the agent snapshot. You can save an inline block as a prompt block to reuse it.
Prompt block reference	A pointer to a saved prompt block. The content is resolved at runtime from the referenced block.

To turn an inline block into a reusable prompt block, open the block's menu and select Save as prompt block. To reference an existing prompt block, select Add block and pick one from the dialog.

Template variables

Prompt blocks support {{variable}} syntax for dynamic content. Variables are resolved at runtime from the agent's variables and request context.

You are helping {{userName}} with their {{task || 'request'}}.

Syntax	Behavior
{{variableName}}	Replaced with the variable value. Left as-is if not found.
{{nested.path.value}}	Resolves dot-notation paths in the context object.
{{variable || 'default'}}	Uses the fallback value when the variable is missing. Single or double quotes are accepted.

Variables are passed through the agent's variables configuration or through request context.

Display conditions

Each block can have a display condition. A rule group that controls whether the block is included in the final prompt. Conditions are evaluated at runtime against the agent's variables and request context.

A rule group uses AND or OR logic with one or more conditions. Each condition checks a context field against a value using an operator:

Operator	Description
equals / not_equals	Exact match comparison.
contains / not_contains	String inclusion or array membership.
greater_than / less_than	Numeric comparison.
greater_than_or_equal / less_than_or_equal	Numeric comparison with equality.
in / not_in	Checks if a value is in an array.
exists / not_exists	Checks if the field is present.

Rule groups can be nested, so you can combine AND and OR conditions for complex logic.

In the Studio, open a block's Display conditions panel to set up rules visually. You can also configure conditions programmatically through the API. Blocks without conditions are always included.

Versioning

Prompt blocks follow the same versioning lifecycle as agents. Each prompt block has a draft that you can edit and publish as a versioned snapshot. This means prompt content can be versioned and rolled back independently from the agent that uses it.

When an agent references a prompt block, the resolved content comes from the block's active published version by default. During editing, draft content is used for previews. This separation makes it safe for non-technical team members to experiment with prompt wording. The published version stays stable until they explicitly activate a new one.

Related

• Editor overview: Setup and versioning.
• MastraEditor reference: Full configuration options for the editor.