> For the complete documentation index, see [llms.txt](https://docs.umbraco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbraco.com/ai-in-umbraco/17.latest/add-ons/prompt/getting-started.md).

# Getting Started

This guide walks you through creating and using your first prompt.

## Prerequisites

Before starting, ensure you have:

* Umbraco.AI installed and configured
* At least one AI connection set up
* At least one chat profile created

## Step 1: Install the Package

{% code title="Package Manager Console" %}

```powershell
Install-Package Umbraco.AI.Prompt
```

{% endcode %}

Restart your application to run database migrations.

## Step 2: Create a Prompt in Backoffice

1. Navigate to the **AI** section > **Prompts**
2. Click **Create Prompt**
3. Fill in the details:

| Field        | Value                                  |
| ------------ | -------------------------------------- |
| Alias        | `meta-description`                     |
| Name         | Generate Meta Description              |
| Description  | Creates SEO-friendly meta descriptions |
| Instructions | See below                              |
| Profile      | (select your chat profile)             |

**Instructions:**

```
Write a meta description for this web page.

Title: {{pageTitle}}
Content: {{bodyText}}

Requirements:
- Maximum 155 characters
- Include the main topic
- Be compelling and action-oriented
- Do not include quotes
```

Variables such as `{{pageTitle}}` and `{{bodyText}}` resolve to properties on the entity the prompt is executed against. Replace them with the property aliases used in your own content types.

4. Click **Save**

## Step 3: Test the Prompt

In the prompt editor, use the **Test** panel to run the prompt against an existing document. The prompt executes using the real entity context, so variables resolve from that document's property values. Review the response in the test output.

## Step 4: Use in Code

### Via Service

Prompt templates resolve their variables from the runtime context that is built around the target entity. `{{pageTitle}}` and `{{bodyText}}` in the instructions map to properties on the document identified by `EntityId`.

{% code title="MetaDescriptionGenerator.cs" %}

```csharp
public class MetaDescriptionGenerator
{
    private readonly IAIPromptService _promptService;

    public MetaDescriptionGenerator(IAIPromptService promptService)
    {
        _promptService = promptService;
    }

    public async Task<string> GenerateAsync(Guid contentKey)
    {
        var prompt = await _promptService.GetPromptByAliasAsync("meta-description");

        var result = await _promptService.ExecutePromptAsync(
            prompt!.Id,
            new AIPromptExecutionRequest
            {
                EntityId = contentKey,
                EntityType = "document",
                PropertyAlias = "metaDescription",
                ContentTypeAlias = "article"
            });

        return result.Content;
    }
}
```

{% endcode %}

### Via API

{% code title="cURL" %}

```bash
curl -X POST "https://your-site.com/umbraco/ai/management/api/v1/prompts/meta-description/execute" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entityId": "8c9a4e8f-2e89-4b3e-9a6f-1c2d3e4f5a6b",
    "entityType": "document",
    "propertyAlias": "metaDescription",
    "contentTypeAlias": "article"
  }'
```

{% endcode %}

## Step 5: Add Contexts (Optional)

To include brand voice in your prompt:

1. Create a Context with your tone guidelines
2. Edit your prompt
3. In the **Contexts** section, add your context
4. The context content will be included in the system message

## Step 6: Configure Scoping

Scoping controls where the prompt is allowed to run. A prompt with no allow rules is not available anywhere, so you need at least one allow rule before the prompt appears in the backoffice.

1. Edit your prompt
2. Expand the **Scope** section
3. Add an **Allow Rule** and choose the content types, properties, or property editors where the prompt should appear
4. Optionally add **Deny Rules** to exclude specific places
5. Save

See [Scoping](/ai-in-umbraco/17.latest/add-ons/prompt/scoping.md) for full details on allow and deny rules.

## Next Steps

* Create more prompts for different use cases
* Explore [Template Syntax](/ai-in-umbraco/17.latest/add-ons/prompt/template-syntax.md) for advanced variables
* Learn about [Scoping](/ai-in-umbraco/17.latest/add-ons/prompt/scoping.md) for allow and deny rules
* Review the [API Reference](/ai-in-umbraco/17.latest/add-ons/prompt/api.md) for programmatic access


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.umbraco.com/ai-in-umbraco/17.latest/add-ons/prompt/getting-started.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.