> 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/extending/knowledge-sets.md).

# Knowledge Sets

Ship background knowledge about your product to the AI by dropping a decorated class into your package.

A knowledge set is a collection of background knowledge about a subject — for example, a product such as Umbraco Engage. It is defined in code and shipped inside a package, so the AI can draw on it.

A package author ships knowledge by dropping a single decorated class into an assembly. The set is discovered at startup, needs no configuration, and its content flows to the model on demand.

Knowledge sets are the content complement to [Contexts](/ai-in-umbraco/concepts/contexts.md): context resource types define the *shape* of context, while knowledge sets provide ready-made *content*.

## Overview

Each knowledge set:

* Has a stable ID, a display name, and an optional description and icon
* Contains one or more **items** (shown as "Topics" in the backoffice), each a chunk of markdown
* Is auto-discovered at startup via the `[AIKnowledgeSet]` attribute — no registration code
* Is auto-active — installed sets are available to every request with nothing to configure
* Is surfaced **on demand** — the model retrieves an item's content only when it is relevant

## How It Works

Installed knowledge sets flow through the same context resolution pipeline as contexts. For each request, the AI is shown a grouped list of the available items, where each item's name and description act as a breadcrumb. The model then pulls an item's full markdown content only when it decides the item is relevant. Item content is produced lazily, so listing a set never loads its content.

## Creating a Knowledge Set

Derive from `AIKnowledgeSetBase`, decorate the class with `[AIKnowledgeSet]`, and override `GetItemsAsync` to return the items. Use `AIKnowledgeSetItem.FromContent` for static markdown:

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

```csharp
using Umbraco.AI.Core.Contexts.KnowledgeSets;

[AIKnowledgeSet("umbraco-engage", "Umbraco Engage",
    Description = "Background knowledge about Umbraco Engage.",
    Icon = "icon-book")]
public sealed class EngageKnowledgeSet : AIKnowledgeSetBase
{
    public override Task<IReadOnlyList<AIKnowledgeSetItem>> GetItemsAsync(
        CancellationToken cancellationToken = default)
    {
        IReadOnlyList<AIKnowledgeSetItem> items =
        [
            AIKnowledgeSetItem.FromContent(
                key: "goals",
                name: "Goals",
                content: "# Goals\nEngage goals let you track conversions across a visit...",
                description: "How goals work in Umbraco Engage."),
        ];

        return Task.FromResult(items);
    }
}
```

{% endcode %}

That is the complete happy path. On startup the class is discovered, and its items become knowledge the AI can draw on — no further wiring required.

### Loading Content Dynamically

`FromContent` wraps a literal string. When an item's content needs to be built at request time — for example loaded from a service — set `GetContentAsync` directly instead. The producer is invoked lazily, only when the content is retrieved:

{% code title="Dynamic item" %}

```csharp
new AIKnowledgeSetItem
{
    Key = "segments",
    Name = "Segments",
    Description = "The audience segments configured on this site.",
    GetContentAsync = async token => await _segmentService.GetSegmentsMarkdownAsync(token),
}
```

{% endcode %}

## AIKnowledgeSetItem

| Property          | Type                                    | Description                                                                                                              |
| ----------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `Key`             | `string`                                | Stable, URL-safe identity within the set (for example `"goals"`). Keep it stable across renames.                         |
| `Name`            | `string`                                | Display name, shown in the backoffice.                                                                                   |
| `Description`     | `string?`                               | The breadcrumb the AI sees when the item is advertised — write it to help the model decide whether to retrieve the item. |
| `GetContentAsync` | `Func<CancellationToken, Task<string>>` | Lazily produces the markdown content, injected as-is when retrieved.                                                     |

## Registration

Knowledge sets are auto-discovered via the `[AIKnowledgeSet]` attribute and the `IDiscoverable` interface. No manual registration is needed.

To turn off a set shipped by another package, exclude it in a Composer:

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

```csharp
using Umbraco.AI.Extensions;
using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;

public class KnowledgeSetComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.AIKnowledgeSets()
            .Exclude<ThirdPartyKnowledgeSet>();
    }
}
```

{% endcode %}

The builder also exposes `.Add<T>()`, but you rarely need it. A decorated set is already registered by discovery. `.Add<T>()` only helps for the uncommon case of a set that implements `IAIKnowledgeSet` directly, without the `[AIKnowledgeSet]` attribute.

## Viewing Installed Knowledge Sets

Installed sets appear under **AI Configuration > Knowledge Sets** in the backoffice. This view is read-only: you can browse the installed sets and open a topic to inspect its content. Knowledge sets are defined in code, so they cannot be created or edited from the backoffice.

## Related

* [Contexts](/ai-in-umbraco/concepts/contexts.md) - Injecting brand voice, guidelines, and content into AI operations
* [Custom Tools](/ai-in-umbraco/extending/tools.md) - Give AI agents actions to perform


---

# 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/extending/knowledge-sets.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.