Context Scope

The Context Scope system allows you to categorize context items by various criteria. Agents can subscribe to scope values to receive the most relevant context for their specific use cases.

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 like "Writing words" and "Working in 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.

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.

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

Language scope detects the current language from the URL
Site Section scope matches the current URL path against configured patterns
Entity Bundle scope detects the current entity's type and bundle
Target Entity scope identifies the entity being worked on

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 seven scope types. Each can be enabled or disabled at /admin/config/ai/context/settings/scope.

Global

Mark context items as global to always include them for every agent. Global items bypass scope matching and are included regardless of an agent's 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 the most recently changed global items first. Items with the same changed time are ordered by item ID descending for deterministic selection.

Agent subscriptions: Not applicable (global items are automatic)
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
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().

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.

Agent subscriptions: Yes
Contextual detection: Yes (detects current language from URL prefix, Referer header, or Drupal language negotiation)
Multiple values: Yes
Management link: /admin/config/regional/language

See the Multilingual documentation for more on languages.

Tag

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

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

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

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 the entity being processed, use the Target entity or Entity bundle scopes 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.)

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

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.

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 bundle

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 Target entity, which matches specific entity instances, entity bundle 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-bundle.

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-bundle

Target entity

Associate context items with specific content entities (nodes, media, taxonomy terms, etc.) using dynamic entity references. When an agent operates on one of the targeted entities, the associated context items are prioritized.

Target entities are set directly on the context item form via the Target entities field, rather than through the scope checkboxes.

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)