Skip to content

Context Scope

The Context Scope system describes where context items apply and how consumers rank them. Agents and other consumers can subscribe to scope values to prioritize relevant context, but a matching subscription does not guarantee that an item reaches the final prompt.

How scopes work

Each scope defines a set of values that can be assigned to Context Items. For example, the Use Case scope has values such as Working with Text and Working with Canvas. The Language scope has values for each language configured on your site.

When editing a context item, you select which scope values apply. When configuring an agent, you select which scope values the agent should prioritize. The scope resolver then scores each context item based on how well its scope values align with the agent's subscriptions.

Selection has several stages:

  1. Published, accessible items become candidates.
  2. Explicit exclusions and contextual mismatches remove items.
  3. Global, situation-based auto-included, and explicitly included items receive their existing priority.
  4. Remaining applicable items are scored against subscriptions.
  5. Global-item and token limits determine the final rendered result.

Scope matching

The AiContextScopeResolver service scores context items against scope subscriptions and applies hard context filters. Items that match more subscribed scope values receive higher scores and are more likely to be selected.

Scope weight controls both scoring influence and display order. The built-in order is Global, Use Case, Entity Types, Site Section, Context Tags, Language, Taxonomy Terms, and Specific Entities. Global and Specific Entities do not participate in subscription scoring. Custom scopes appear according to their declared weight. Weights below 1 are treated as 1 during subscription scoring only.

These are separate operations. Language, Site Section, Entity Types, and Taxonomy Terms can all filter by the current situation and contribute to subscription scoring. Use Case and Context Tags contribute only to subscription scoring. Specific Entities filters and auto-includes exact matches but does not support subscriptions. One matching scope does not override another scope that rejects an item.

Some scopes also support contextual detection -- they can automatically determine the current value from the request context. For example:

  • Language scope uses the shared content-language detector (path prefix, same-site Referer, then Drupal content-language negotiation)
  • Site Section scope matches the current URL path against configured patterns
  • Entity Types scope detects the current entity's type and bundle
  • Taxonomy Terms scope reads taxonomy references on the current entity
  • Specific Entities scope identifies the entity being worked on

Leaving a scope blank on a Context Item means that the scope does not restrict the item. During subscription scoring, a blank scope receives full credit as generic context.

See Context Selection for the complete pipeline, priority order, scoring rules, selection modes, and limits.

Scope settings

Manage scopes at /admin/config/ai/context/settings/scope. Each scope can be individually enabled or disabled. Some scopes have additional settings (e.g., Site Section has configurable URL patterns).

For custom scope plugins, see Custom scopes.

Built-in scopes

The AI Context module ships with eight scope types. Each can be enabled or disabled at /admin/config/ai/context/settings/scope.

Global

Mark context items as global to give them priority for every agent. Global items bypass scope matching and do not require agent subscriptions.

When you save a context item with global enabled, previous scope settings on that item are cleared. Leave global disabled to configure scope filters and categories instead.

When more published global items exist than the configured global item limit, the selector includes higher Priority values first. When priority ties, shorter content is preferred. The highest item ID breaks remaining ties for deterministic selection.

Global items remain subject to publication, view access, Never include, global-item, and token limits. Global items are considered before per-agent Always include overrides during merge. Global and Always include settings give items priority; neither guarantees that complete content reaches the prompt. Do not use them as the only delivery control for compliance-critical instructions.

  • Agent subscriptions: Not applicable (global items apply to every agent)
  • Contextual detection: Not applicable
  • Multiple values: No (global is a boolean toggle)

Use case

Categorize context items by the type of task they support. Default values (ordered alphabetically in the UI):

  • Working with Canvas (working_with_canvas) -- for agents that operate in a visual canvas editor. Requires Canvas 1.8.0 or later on Canvas-enabled sites; see Canvas sites.
  • Working with Media (working_with_media) -- for agents that work with images, video, or other media
  • Working with People (working_with_people) -- for agents that help with people-related tasks such as profiles or team content
  • Working with Text (working_with_text) -- for agents that help create or edit text content

Additional values can be added via hook_ai_context_scope_values_alter().

Use Case matching example

Assume these Context Items:

  • TC has Working with Text and Working with Canvas.
  • T has only Working with Text.
  • C has only Working with Canvas.
  • U has no Use Case values.

When Use Case is the only subscription, a Text subscription considers TC, T, and U. A Canvas subscription considers TC, C, and U. A subscription to both values ranks TC and U highest; T and C receive half of the available Use Case credit.

Use Case does not inspect the current page or the user's task. U is generic and receives full Use Case credit for every subscription.

  • Agent subscriptions: Yes
  • Contextual detection: No
  • Multiple values: Yes

Language

Scope context items to specific languages configured on your site. The available values are automatically populated from Drupal's language configuration.

Language scope is separate from the Context Item entity's language and translations. Scope values determine eligibility and ranking. Entity translations determine which text is injected after an item is selected.

Language matching example

Assume these Context Items:

  • T has English and Spanish translations and English + Spanish scope.
  • E has English scope.
  • S has Spanish scope.
  • U has no Language scope.

With an English subscription, an English request considers T, E, and U. A Spanish request considers T and U because the current-language filter removes E.

With a Spanish subscription, an English request considers T and U. A Spanish request considers T, S, and U.

With only a Use Case subscription, an English request considers T, E, and U, while a Spanish request considers T, S, and U. Language still acts as a hard filter even when the consumer does not subscribe to it. If the current language cannot be determined, Language scope does not remove the item.

After selection, T uses its English translation for an English content language and its Spanish translation for a Spanish content language. U uses its original translation when it has no translation for the detected content language.

The Language scope plugin uses the same content-language detection as translation selection: request path prefix, same-site Referer, then Drupal content-language negotiation.

  • Agent subscriptions: Yes
  • Contextual detection: Yes (shared content-language detector)
  • Multiple values: Yes
  • Management link: /admin/config/regional/language

See the Multilingual documentation for more on languages.

Context Tags

Organize context items using tags from the AI Context Tags taxonomy vocabulary (ai_context_tags, installed with the module). Context Tags provide free-form categorization of context items beyond the structured scope types.

Context Tags work through agent subscriptions, not contextual detection. The typical workflow is:

  1. Add terms to the AI Context Tags vocabulary at /admin/structure/taxonomy/manage/ai_context_tags/overview.
  2. Edit a context item and select one or more tags in the Context Tags scope field.
  3. Configure an agent and subscribe it to the same tags in its context settings.
  4. When that agent runs, context items tagged with the agent's subscribed tags score higher and are more likely to be selected.

Context Tag scope does not read tags from the entity an agent is working on. There is no automatic matching against a taxonomy reference field on the current node, media item, or other content entity. To prioritize context based on taxonomy terms referenced by the entity being processed, use the Taxonomy Terms scope instead. (A custom module can supply a current tag value at runtime with hook_ai_context_scope_values_alter(), but the module ships no such behavior for Context Tags.)

Context Tags matching example

Assume BL has Brand and Legal, B has only Brand, L has only Legal, and U has no Context Tags scope. When Context Tags are the only subscription, a Brand subscription considers BL, B, and U. A Legal subscription considers BL, L, and U. A subscription to both tags ranks BL and U highest; B and L receive half of the available Context Tag credit.

Matching uses taxonomy term IDs, not labels. Context Tags do not inspect the current entity or user task.

  • Agent subscriptions: Yes
  • Contextual detection: No
  • Multiple values: Yes
  • Management link: /admin/structure/taxonomy/manage/ai_context_tags/overview

Taxonomy Terms

Associate context items with taxonomy terms from your site's vocabularies. When the current content entity references matching terms, those context items pass the hard context filter and can also be prioritized through agent subscriptions.

The context item form lists each site vocabulary (except AI Context Tags) with its own autocomplete field. Stored values are taxonomy term IDs. Values are not preloaded into checkbox options because large vocabularies would be too expensive to load on every form build.

Note: The AI Context Tags vocabulary (ai_context_tags) is excluded because it is reserved for the Context Tags scope. Context Tags categorize context items for agent subscriptions and do not inspect taxonomy references on the current content entity. Use Context Tags when you want tag-based agent subscriptions; use Taxonomy Terms when context should match site vocabularies referenced by the entity being processed, such as Topics or Categories.

Taxonomy Terms matching example

Assume C is scoped to Climate, CS to Climate and Sports, and U has no Taxonomy Terms values.

  • While viewing an Article tagged Climate, Sports, and Events, C, CS, and U pass the hard filter.
  • While viewing a Blog post tagged only Climate, C, CS, and U pass the hard filter.
  • While viewing content tagged only Sports, CS and U pass the hard filter.
  • If no current entity can be resolved, C and CS fail the hard filter; U still passes.

Any matching term is enough for a scoped item to pass. Matching uses taxonomy term IDs, not labels.

  • Agent subscriptions: Yes
  • Contextual detection: Yes (reads taxonomy reference fields on the current entity)
  • Multiple values: Yes
  • Management link: /admin/structure/taxonomy

Site section

Scope context items to URL path patterns. This allows context to be associated with specific sections of your site based on URL structure.

Patterns support wildcards:

  • /blog/* -- matches any path under /blog/
  • /products/* -- matches any path under /products/
  • /about -- matches the exact /about path

Site sections can include both predefined patterns (configured in settings) and custom patterns added per context item.

If there is no current request, items with Site Section values are rejected. Items without Site Section values remain unrestricted by this scope.

Site Section matching example

Assume B uses a predefined Blog section with /blog/*, P uses the custom pattern /products/*, BP uses both, and U has no Site Section values.

  • On /blog/post-1, B, BP, and U pass the hard filter.
  • On /products/widget, P, BP, and U pass the hard filter.
  • On /contact, only U passes the hard filter.
  • Without a current request, only U passes the hard filter.

Any matching value is enough for a scoped item to pass. Patterns match the complete path, with * as a wildcard.

Agent subscriptions score surviving items by overlap with their stored section values. Custom patterns in subscriptions are compared as literal stored values; subscription scoring does not independently evaluate those patterns against the current URL.

  • Agent subscriptions: Yes
  • Contextual detection: Yes (matches current request URL against configured patterns)
  • Multiple values: Yes
  • Settings form: /admin/config/ai/context/settings/scope/site_section

Entity Types

Scope context items to entity type and bundle combinations (for example, node:article). Active whenever the current page involves an entity of a matching bundle — on the frontend (viewing a blog post) or in the admin UI (editing or revising that post).

Unlike Specific Entities, which matches individual entities, the Entity Types scope applies to every entity in the configured bundle.

Values are built dynamically from the entity types enabled in scope settings at /admin/config/ai/context/settings/scope/entity-type.

Entity Types matching example

Assume A is scoped to Content: Article, P to Content: Basic page, AP to both bundles, and U has no Entity Types values.

  • While working with an Article, A, AP, and U pass the hard filter.
  • While working with a Basic page, P, AP, and U pass the hard filter.
  • If no current entity can be resolved, only U passes the hard filter.

Agent subscriptions then score the surviving items by literal entity_type:bundle overlap. Entity Types matches do not enter the situation-based auto-inclusion tier; this scope supports ordinary subscriptions and scoring.

If no current entity type can be resolved, items with Entity Types values are rejected. Items without Entity Types values remain unrestricted by this scope.

  • Agent subscriptions: Yes
  • Contextual detection: Yes (resolves entity type and bundle from the current route or request context)
  • Multiple values: Yes
  • Settings form: /admin/config/ai/context/settings/scope/entity-type

Specific Entities

Associate context items with specific content entities (nodes, media, taxonomy terms, etc.) using dynamic entity references. When a consumer operates on one of the targeted entities, the associated Context Items are auto-included in the situation-based priority tier. They still respect publication, access, exclusion, and token limits.

Specific entities are set directly on the context item form using the entity reference field within this scope, rather than through the scope checkboxes.

Specific Entities matching example

Assume 123 targets Article #123, 456 targets Article #456, and U has no specific entities.

  • While working with Article #123, 123 is auto-included, 456 is removed, and U remains an ordinary candidate.
  • While working with Article #456, 456 is auto-included, 123 is removed, and U remains an ordinary candidate.
  • Without a current entity, both targeted items are removed and U remains.

An item with multiple targets matches when any target matches. Specific Entities matches an exact entity instance; use Entity Types to apply context to every entity in a bundle.

  • Agent subscriptions: Not applicable (context is applied based on the entity being worked on, not agent configuration)
  • Contextual detection: Yes (resolves the current entity from the route or request context)
  • Multiple values: Yes (can target multiple entities)

For subcontext items with inherit_parent_scope enabled, entity item matching uses the parent's entity items, not values stored on the child. See Parent scope.

Worked examples

Subscription match does not guarantee selection

An item tagged Editorial matches a consumer's Tag subscription. That match improves the item's score, but another item may still be selected first when the token budget is reached or when other applicable items score higher.

Contextual mismatch excludes an item

An item has Use Case = Working with Text and Language = French. The consumer subscribes to Working with Text, but the current context is English. The use-case match improves ranking only after hard filters pass; the language mismatch makes the item inapplicable for that request.

Entity Types is applicability, not a guarantee

An Article editorial standards item is scoped to node:article. When the consumer works with an article, the item is applicable and can be scored against Entity Types subscriptions. It is not guaranteed to survive ranking and the token budget.

Specific Entities differs from Entity Types

An item that targets Article #123 is considered only when the consumer is working with Article #123. A match uses the situation-based priority tier. Entity Types such as node:article apply more broadly to every article bundle item and use ordinary subscription scoring.

Explicit override

A consumer's Always include override gives an item priority independently of ordinary subscription scoring and hard context filters. The item must still be published and accessible, and the rendered content can still be shortened or omitted by the token limit. Never include wins over Always include.

Global context

A Global item does not require a subscription. The item must still be published and accessible. If more published global items exist than the configured global-item limit, the selector uses Priority, then shorter content, then the highest item ID to choose which global items enter the selection set. The token budget still controls what is rendered.