> 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/concepts/contexts.md).

# Contexts

Contexts define brand voice, guidelines, and additional content that get injected into AI operations.

A context is a collection of resources that provide additional information to AI operations. Contexts enable you to maintain consistent brand voice, inject guidelines, or include relevant content (like retrieval-augmented generation (RAG) data) into every AI request.

## What Contexts Store

| Property    | Description                                  |
| ----------- | -------------------------------------------- |
| `Id`        | Unique identifier (GUID)                     |
| `Alias`     | Unique string for programmatic lookup        |
| `Name`      | Display name shown in the backoffice         |
| `Resources` | Collection of context resources              |
| `Version`   | Current version number (for version history) |

## Context Resources

Each context contains one or more resources. A resource represents a piece of content that gets injected into AI requests.

| Property         | Description                                     |
| ---------------- | ----------------------------------------------- |
| `Id`             | Unique identifier (GUID)                        |
| `ResourceTypeId` | The type of resource (e.g., "text", "document") |
| `Name`           | Display name for the resource                   |
| `Description`    | Optional description                            |
| `SortOrder`      | Controls injection order                        |
| `Settings`       | Type-specific settings                          |
| `InjectionMode`  | When the resource is injected                   |

### Injection Modes

Resources can be injected based on different conditions:

| Mode       | Description                                         |
| ---------- | --------------------------------------------------- |
| `Always`   | Resource is always included (default)               |
| `OnDemand` | Resource is included only when explicitly requested |

## Using Contexts in Code

### Getting a Context

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

```csharp
public class ContextExample
{
    private readonly IAIContextService _contextService;

    public ContextExample(IAIContextService contextService)
    {
        _contextService = contextService;
    }

    public async Task<AIContext?> GetBrandContext()
    {
        return await _contextService.GetContextByAliasAsync("brand-voice");
    }
}
```

{% endcode %}

### Creating a Context

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

```csharp
using Umbraco.AI.Core.Contexts.ResourceTypes.BuiltIn;

public async Task<AIContext> CreateContext()
{
    var context = new AIContext
    {
        Alias = "brand-guidelines",
        Name = "Brand Guidelines",
        Resources = new List<AIContextResource>
        {
            new AIContextResource
            {
                ResourceTypeId = "text",
                Name = "Tone of Voice",
                Description = "Writing style guidelines",
                SortOrder = 0,
                Settings = new TextResourceSettings
                {
                    Content = "Always use a friendly, professional tone..."
                }
            }
        }
    };

    return await _contextService.SaveContextAsync(context);
}
```

{% endcode %}

## How Context Injection Works

When an AI operation executes with contexts:

1. All associated contexts are retrieved.
2. Resources are sorted by `SortOrder`.
3. Resources with matching `InjectionMode` are selected.
4. Resource content is formatted and injected into the system message.
5. The AI model receives the enriched request.

When multiple contexts are used, they are processed in the order they are listed. Within each context, resources are processed by `SortOrder`, and all resource content is concatenated into the system context.

## Managing Contexts

### Via Backoffice

You can create, edit, and delete contexts through the backoffice. See [Managing Contexts](/ai-in-umbraco/backoffice/managing-contexts.md) for step-by-step instructions.

### Via Code

For programmatic context management, see the [IAIContextService](/ai-in-umbraco/reference/services/ai-context-service.md) reference.

## Version History

Contexts support version history. Every time you save a context, a new version is created. You can:

* View the version history.
* Compare different versions.
* Roll back to a previous version.

See [Version History](/ai-in-umbraco/concepts/versioning.md) for more information.

## Related

* [Profiles](/ai-in-umbraco/concepts/profiles.md) - Use contexts with AI profiles
* [Version History](/ai-in-umbraco/concepts/versioning.md) - Track context changes over time
* [Managing Contexts](/ai-in-umbraco/backoffice/managing-contexts.md) - Backoffice guide
* [Knowledge Sets](/ai-in-umbraco/extending/knowledge-sets.md) - Ship background knowledge from a package in code


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.umbraco.com/ai-in-umbraco/concepts/contexts.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.