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/config/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.

Import content

When the optional ai_context_document_loader submodule is enabled, a Load Document button appears in the MDXEditor toolbar. Editors can import text, Markdown, PDF, or URL content directly into this field. See Content importers for installation, supported sources, and usage.

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)

Optional parent context item when subcontext hierarchy is enabled. Child items are included when their parent is selected for an agent.

See Subcontext hierarchies for required vs conditional types, when to use subcontext, limits, and the site-wide toggle.

Persistence rules (subcontext)

When subcontext hierarchy is enabled, relationships are validated on save:

  • 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 remain as standalone items with their parent and subcontext_type fields cleared

Canonical view page

Opening a context item at /admin/config/ai/context/items/{id} (or viewing a revision) uses the full view mode and ai-context-item--full.html.twig instead of the default field list (ai-context-item.html.twig).

Main column

Rendered from the full view display field formatters:

  • Description
  • Purpose
  • Content
  • Content moderation control (when Content Moderation is enabled)

The page title is the entity label on the canonical route. Revision view uses the standard revision page title from the route.

A custom status badge shows the moderation state or published flag.

Built by AiContextItemViewBuilder (not field formatters):

  • Last updated date and author (plain text with avatar initial)
  • Subcontext type (when viewing a child item)
  • Scope plugin values. Global items show only Global: Enabled (matching the edit form). When at least one non-global scope is set, all enabled scope rows are shown (global first as Disabled, empty scopes as None in italics). When no non-global scopes are set, a SCOPE heading and italic message (No scope plugins are in use) are shown instead. Custom site section patterns list each path; entity bundle labels collapse when the type and bundle names match (e.g. Page: Page → Page). Each row includes a Phosphor icon via the shared .ai-icon pattern and SVGs bundled in this module.

Shown only when the item or its parent has subcontext children. Lists sibling child items with links and highlights the current item.

On revision view routes, the Nav panel lists subcontext siblings that existed when the viewed revision was saved (based on each child's parent reference at that point in time). Canonical view routes use the live child list.

Fields hidden on full view

These are omitted from the full view display because the template or AiContextItemViewBuilder handles them: label, parent, subcontext type, langcode, scope, tags, uid.

Duplicating items

Context items can be duplicated via the Duplicate tab on any existing item (/admin/config/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/config/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