Prompts
Trust: ★★★☆☆ (0.90) · 0 validations · developer_reference
Published: 2026-05-10 · Source: crawler_authoritative
Tình huống
Mastra agent prompt management documentation for creating reusable instruction blocks with variables, display conditions, and versioning through Studio UI or programmatic API.
Insight
Prompt blocks are reusable instruction templates composed into an agent’s system prompt. Each block supports {{variable}} syntax for dynamic content with dot-notation path resolution ({{nested.path.value}}) and fallback values ({{variable || 'default'}}). Display conditions control block inclusion using rule groups with AND/OR logic. Supported operators include: equals, not_equals, contains, not_contains, greater_than, less_than, greater_than_or_equal, less_than_or_equal, in, not_in, exists, not_exists. Block types are: inline text (agent-specific free-form text), prompt block (standalone stored block), and prompt block reference (runtime-resolved pointer to a saved block). Prompt blocks follow versioning with draft/publish lifecycle, resolving content from the active published version at runtime by default. The editor API provides methods: editor.prompt.create(), editor.prompt.update(), editor.prompt.list(), editor.prompt.getById(), and editor.prompt.preview(). HTTP endpoints: GET /stored/prompt-blocks, POST /stored/prompt-blocks, GET /stored/prompt-blocks/:storedPromptBlockId, PATCH /stored/prompt-blocks/:storedPromptBlockId, DELETE /stored/prompt-blocks/:storedPromptBlockId. Agents reference blocks via { type: 'prompt_block_ref', id: 'block-id' } in their instructions array.
Hành động
- Create prompt block via Studio UI (Prompts tab → Create prompt → enter name and instruction text → Save and publish) or programmatically via
editor.prompt.create({ id, name, description, content }). 2. Open agent’s Instructions section and select Add block to reference the prompt block from the block picker dialog. 3. Variables are resolved at runtime from agent’svariablesconfig or request context. 4. Set display conditions via block’s Display conditions panel or programmatically. 5. To update, calleditor.prompt.update({ id, content })which creates a new draft version. 6. Publish draft versions to activate them; draft content is used for previews, published versions for runtime. 7. Non-technical team members can safely edit drafts while published versions remain stable until explicitly activated. 8. Roll back by selecting a previous published version.
Kết quả
Prompt blocks render as references in the agent’s instruction list. Changes to the original prompt block automatically propagate to all referencing agents. Variables resolve at runtime from request context. Blocks without display conditions are always included. Published versions remain stable until explicitly activated.
Nội dung gốc (Original)
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
- Go to the Prompts tab in Studio.
- Select Create prompt and enter a name and your instruction text.
- Save the prompt block and publish it.
- Open an agent’s Instructions section and select Add block.
- 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.
Programmatic control
Prompt blocks can be managed from code through mastra.getEditor().prompt. This is useful for seeding a set of starter prompts, syncing blocks between environments, or generating prompt variants from a script.
Create a new prompt block with editor.prompt.create():
import { mastra } from '../mastra'
const editor = mastra.getEditor()!
await editor.prompt.create({
id: 'brand-voice',
name: 'Brand voice',
description: 'Acme Inc. tone and style guidelines',
content:
'You write in a friendly, concise tone. Always address the user as {{userName || "there"}}.',
})Update an existing block with editor.prompt.update(). Each update creates a new draft version:
import { mastra } from '../mastra'
const editor = mastra.getEditor()!
await editor.prompt.update({
id: 'brand-voice',
content: 'You write in a friendly, concise tone. Always greet the user by name when available.',
})Use editor.prompt.list() to paginate through stored blocks or editor.prompt.getById() to fetch a specific block. To preview an agent’s full instructions with a set of prompt blocks applied, call editor.prompt.preview() with the draft content.
The same operations are available over HTTP through the Mastra server:
| Method | Path | Description |
|---|---|---|
GET | /stored/prompt-blocks | List all stored prompt blocks. |
POST | /stored/prompt-blocks | Create a stored prompt block. |
GET | /stored/prompt-blocks/:storedPromptBlockId | Get a stored prompt block by ID. |
PATCH | /stored/prompt-blocks/:storedPromptBlockId | Update a stored prompt block. |
DELETE | /stored/prompt-blocks/:storedPromptBlockId | Delete a stored prompt block. |
Once a prompt block is created, reference it from an agent’s instructions field as a prompt_block_ref:
import { mastra } from '../mastra'
const editor = mastra.getEditor()!
await editor.agent.update({
id: 'support-agent',
instructions: [
{ type: 'prompt_block_ref', id: 'brand-voice' },
{ type: 'text', content: 'Answer only questions about Acme products.' },
],
})Note: See the MastraEditor reference for the full
editor.promptAPI.
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.
Liên kết
- Nền tảng: Dev Framework · Mastra
- Nguồn: https://mastra.ai/docs/editor/prompts
Xem thêm: