Umbraco AI Prompts: Template Syntax and Variables

Following on from my Introducing Umbraco AI post, I wanted to dig deeper into one of the add-on packages that I think has the most immediately practical value for content editors: Umbraco.AI.Prompt.

I’ve had a few questions about how prompt templates work, what variables are available, and — one that comes up a lot — how to work with images in prompts. So let’s break it all down.

What Are Prompts?

Prompts are executable AI instructions that run directly inside the Umbraco backoffice. When you install the Umbraco.AI.Prompt package, you can define prompt templates that appear as property actions on content editors. A content editor can click a prompt action on any supported property and get AI-generated values with a single click — things like “Generate an SEO title”, “Summarize this content”, or “Generate alt text for this image”.

Each prompt is configured in the backoffice with:

A template (the instruction sent to the AI)
A profile (which AI provider/model to use)
A display mode — either Property Action (appears as an action button on supported properties) or TipTap Tool (appears in the rich text editor toolbar dropdown)
Scope rules (which properties and content types the prompt appears on)
An Include Entity Context toggle
The number of options to generate

The template is where things get interesting.

Template Syntax

Prompt templates use Mustache-style double curly braces to reference dynamic values:

Generate a meta description for: {{heading}}

When the prompt executes, {{heading}} is replaced with the actual value of the heading property on the content being edited. Simple as that.

You can reference any property alias from the current entity, and you can use multiple variables in a single template:

Write a social media post about "{{heading}}" based on the following content:
{{bodyText}}

Available Variables

Here’s the full list of variables available in prompt templates:

Entity Property Values

Any property alias from the current content node is available as a template variable. If your document type has properties with aliases heading, bodyText, author, publishDate — you can reference all of them:

Variable	Resolves To
`{{heading}}`	Value of the “heading” property
`{{bodyText}}`	Value of the “bodyText” property
`{{author}}`	Value of the “author” property
…any alias	…that property’s value

These come from the serialized entity context that the backoffice sends with the prompt execution request.

Built-in Variables

Beyond property values, several built-in variables are always available:

Variable	Description	Example Value
`{{currentValue}}`	The current value of the property being edited	`"My existing title"`
`{{selection}}`	Any text the user has selected (useful for rich text)	`"selected paragraph"`
`{{entityId}}`	The entity’s unique identifier (GUID)	`"a1b2c3d4-..."`
`{{entityType}}`	The type of entity	`"document"`, `"media"`
`{{entityName}}`	The display name of the entity	`"About Us"`
`{{contentType}}`	The content type alias	`"articlePage"`
`{{propertyAlias}}`	The alias of the property being edited	`"metaTitle"`
`{{culture}}`	The current language variant	`"en-US"`
`{{segment}}`	The current segment variant	`"default"`

{{currentValue}} is particularly useful for refinement prompts — where you want the AI to improve an existing value rather than generate from scratch:

Improve the following title to be more engaging while keeping it under 60 characters:
{{currentValue}}

And {{selection}} opens up some interesting possibilities for prompts with the TipTap Tool display mode — an editor can select a paragraph in the rich text editor and run a prompt against just that selection:

Rewrite the following to be more concise:
{{selection}}

Note that {{selection}} is only populated for TipTap Tool prompts, since that’s the context where text selection is available.

Working with Images

This is the one that catches people out. If you want the AI to see an image — for example, to generate alt text — you need to use the image: prefix:

{{image:umbracoFile}}

Not {{umbracoFile}}.

Without the image: prefix, you just get the raw property value — typically a JSON string like {"src":"/media/abc123/photo.jpg"} or a GUID. The AI receives text, not an image, and understandably responds with “I can’t see any image”.

The image: prefix triggers multimodal content resolution. Here’s what happens behind the scenes:

The property value is read from the entity (supporting media picker JSON, image cropper JSON, GUIDs, and file paths)
The actual image binary is fetched from the media system
The image is sent to the AI as multimodal content (binary data + MIME type) alongside the text prompt

So for alt text generation on a media item, your prompt template should look like:

Write concise, descriptive alt text in under 125 characters for the following image:
{{image:umbracoFile}}
Return only the alt text.

This works with any property that holds a media reference — umbracoFile on media items, or a media picker property on documents.

Note: Image-based prompts require a provider and model that supports vision/multimodal input. Most modern models (GPT-4o, Claude, Gemini) support this, but check your provider’s capabilities.

Nested Path Resolution

For more complex data structures, the template engine supports nested path expressions:

{{user.name}}              — dot notation for nested objects
{{data["complex.key"]}}    — bracket notation for keys containing dots
{{items[0].value}}         — array indexing

Path resolution is case-insensitive, so {{Heading}} and {{heading}} both work. If a path can’t be resolved, it renders as an empty string — no errors.

Include Entity Context

Each prompt has an Include Entity Context toggle. When enabled, all of the entity’s properties are automatically formatted as a markdown document and injected as a system message to the AI. This gives the AI full awareness of the page content without you needing to reference every property individually in your template.

The formatted context looks something like:

## Current Entity Context
Key: a1b2c3d4-...
Name: About Us
Type: document
Content type: articlePage

### Properties

- **Heading** (heading): About Us
- **Body Text** (bodyText): We are a team of...
- **Author** (author): Jane Smith

This is what makes prompts like the following work:

Generate an SEO summary for this page.

With Include Entity Context enabled, the AI knows what “this page” means — it can see the heading, body text, author, and every other property on the content node. Without it, the AI would have no idea what page you’re referring to. It’s a simple toggle that makes a big difference for prompts that need to reason about the content as a whole.

Important: Variable replacement ({{property}}) works regardless of this setting. Include Entity Context just adds extra ambient context for the AI to work with. You can use both together — reference specific properties in your template and give the AI full page awareness at the same time.

Practical Examples

Here are a few prompt templates to give you ideas:

Alt Text Generation (Image)

Write concise, descriptive alt text for accessibility in under 125 characters for this image:
{{image:umbracoFile}}
Return only the alt text.

Remember: the image: prefix is essential. Without it, the AI only sees the file path or JSON metadata as text.

SEO Title Generation

Generate an SEO-optimized title under 60 characters for this page.
The current heading is: {{heading}}

Enable “Include Entity Context” so the AI can consider the full page content, not just the heading.

Content Summary

Summarize the following content in exactly 2 sentences:
{{bodyText}}

Translation

Translate the following text to French.
Preserve any HTML formatting.
Return only the translation.

{{currentValue}}

This works on any property since it uses currentValue — the current value of whatever property the prompt is run against.

Improve Existing Text

Rewrite the following to be more engaging and professional, keeping a similar length:
{{currentValue}}

Set the Options count to 3 so the editor gets multiple variations to choose from.

Wrapping Up

The prompt system is designed to be straightforward for common cases (reference a property, get a value) while being powerful enough for advanced scenarios (multimodal image analysis, nested data, full page awareness).

The main things to remember:

Use {{propertyAlias}} for text values
Use {{image:propertyAlias}} when you need the AI to see an image
Use {{currentValue}} to work with the property being edited
Turn on “Include Entity Context” when the AI needs page-level awareness

If you have questions or want to share prompt templates that work well for you, find me in the Umbraco community Slack or drop a comment below.

Until next time 👋