Skip to content

Subcontext hierarchies

Subcontext lets you organize related context items as a parent with one or more child items (one level deep). When a parent is selected for an agent, its children can be included automatically — either always or only when relevant to the current task.

Subcontext hierarchy is enabled by default. Site builders can turn it off at Context item settings (/admin/config/ai/context/settings/items).

When to use subcontext

  • Large topics — split broad context (for example, "Product catalog") into focused child items ("Electronics", "Clothing", "Home goods").
  • Editorial grouping — keep related detail together under one parent in the admin UI and in agent configuration.
  • Token-focused workflows — use conditional children so detail is included only when the task warrants it (see Token and selection tradeoffs).

When to skip it

  • You have a small, flat set of context items and scopes already narrow selection enough.
  • Your team wants the simplest editorial model first — every item top-level, no parent/child concepts.
  • You are not ready to configure an AI provider for conditional subcontext (required subcontext still works without a provider).

Required vs conditional children

Each child has a subcontext type:

Type Behavior
Required Always included when the parent is selected.
Conditional Included only when Enable conditional subcontext AI decisions is on and the configured AI provider/model decides the child is relevant to the current task. Requires an AI provider/model in general settings.

If Enable conditional subcontext AI decisions is off, all conditional children are included without an AI call.

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

Configure the provider at General settings.

Creating subcontext items

From the context items listing (/admin/config/ai/context/items):

  1. Create or edit a parent (top-level) item.
  2. Use Add subcontext on the parent row to create a child with the parent pre-filled.
  3. Choose Required or Conditional in the subcontext settings fieldset.

See Context items for field descriptions. Persistence rules (one level deep, validation on save) are summarized there.

Token and selection tradeoffs

Required-only subcontext: When a parent is selected, all required children are included. That can use more tokens than a smaller parent alone.

Conditional subcontext: Adds an LLM step to choose which conditional children match the current task. That step has latency and API cost, but may reduce tokens compared to always injecting all child content. Results depend on your provider, prompts, item sizes, and task patterns — there is no guaranteed cost or token savings. Evaluate with your own content and usage tracking.

In all cases, rendering is still capped by Max tokens for injection in general settings; content may be truncated if the budget is exceeded.

Limits interaction

General settings define Max context items to inject and Max tokens for injection:

  1. Parent items (and other selected items) are merged and capped by max items.
  2. Required and conditional children are added after that cap, so the total injected item count may be higher than the max items setting.
  3. Max tokens applies to the final rendered output for all selected items together.

See Configuration for the max items and max tokens settings.

How children get selected

Primary path: A parent is selected (by scope, global rules, always include, or context-auto). Subcontext resolution then loads and filters its children.

Other paths (usually unintentional): A child can also enter selection on its own if it is in the agent's Always include list, matches context-auto rules (such as target entity), or matches scope subscriptions on its own scopes. Subcontext items are designed to ride along with their parent; prefer attaching detail as subcontext rather than giving children independent scopes unless you mean to.

Children appear nested under their parent in agent context settings.

Disabling subcontext hierarchy

When Enable subcontext hierarchy is turned off in context item settings:

  • Parent and subcontext type fields are hidden on item forms.
  • Subcontext resolution is skipped at runtime (children are not auto-included with parents).
  • Warning: Saving any context item clears its parent and subcontext_type values. This is not reversible from the UI.

Re-enable the feature before editing items if you need to preserve hierarchy data.

Planned: tooling to analyze large context items and suggest logical subcontext splits for editorial review (see drupal.org issue #3574929). That complements manual subcontext hierarchy; it does not replace it.

See also