Skip to content

Context Items

Context items are the core content entities in the AI Context module. Each item contains information that AI agents can use when helping with tasks on your Drupal site.

Creating a context item

  1. Go to /admin/ai/context/items
  2. Click Add AI Context Item
  3. Fill in the fields described below
  4. Save the item

Fields

Label

The title of the context item. This is used for identification in admin - Label - Description - Purpose - Content - Context scope - Target entities - Parent (subcontext)

Description

A short summary of the context item's purpose. Helps editors understand what the item covers without reading the full content.

Purpose

An internal note describing why this context item exists. Not sent to agents -- purely for editorial reference.

Content

The main body of the context item, written in markdown using the MDXEditor. This is the text that gets included in agent system prompts when the item is selected.

Context scope

Scope values that categorize this item. See Scopes for details on the scope system.

Target entities

Associate this context item with specific content entities (nodes, media, etc.) using dynamic entity references. When an agent operates on one of these entities, this context item will be prioritized.

Parent (subcontext)

Context items support a parent-child hierarchy. When a parent item is selected for an agent, its children (subcontext items) are automatically included as well.

Subcontext (parent-child hierarchy)

Subcontext allows you to organize context items in a tree structure:

  • A parent item can have one or more child items
  • Required children are included automatically when their parent is selected
  • Conditional children require a configured AI provider/model and are included only when the provider selects them for the current task
  • If a parent is deleted, the parent and subcontext_type fields are cleared from all children to prevent orphaned references

If no AI provider/model is configured, conditional subcontext is unavailable in the item form and existing conditional children are ignored until a provider/model is configured. If provider selection fails at runtime, conditional children are skipped rather than included by default.

This is useful for breaking large context topics into manageable pieces. For example, a parent "Product Catalog" item could have children for "Electronics", "Clothing", and "Home Goods".

Persistence rules

Subcontext relationships are validated when context items are saved, not only when context is selected for an agent:

  • A context item cannot be its own parent
  • Subcontext hierarchies are limited to one level
  • An item that already has children cannot become a subcontext itself
  • subcontext_type is required when a parent is selected
  • If a parent item is deleted, child items keep existing as standalone items with their parent and subcontext_type fields cleared

Duplicating items

Context items can be duplicated via the Duplicate tab on any existing item (/admin/ai/context/items/{id}/duplicate). This creates a copy with all field values pre-filled, which you can then modify and save as a new item.

Managing items

The context items listing at /admin/ai/context/items shows all items with filtering and sorting capabilities. From the listing you can:

  • View, edit, or delete individual items
  • See the current moderation state (draft, published)
  • Access revision history
  • Duplicate items