Skip to content

Consumer configuration

A consumer is anything that receives context: an AI agent, an AI Automator when that module is installed, and other integrations (for example AI CKEditor) when those projects ship a consumer type. Each live instance can have its own override in ai_context.consumers.

Agents are one consumer type. They still get loop-aware injection and Debug / Explore links. Automators and other types do not.

Automator IDs use the canonical form automator:{ai_automator id}. Listing names are the automator label prefixed with the bundle label and a colon (for example Blog: Content Default). A stored label that already starts with the bundle name is rewritten to use the same colon, so Utility page Content Default becomes Utility page: Content Default. The description identifies the field and content type in human-readable form, such as Automator for the Body field on the Article Content type. The listing name links to the field configuration edit form when that field exists and the current user can administer the field. Otherwise it links to the Automator configuration form. Push defaults off. Matching requires the ai_automator:id:{id} request tag. AI core does not emit that tag yet. A temporary internal subscriber adds it when entity type, bundle, and field uniquely identify one automator, or when the clicked widget action UUID maps to one automator on that field. Clicks on any value of a multi-value field map the same way. The same click also skips the other automators on that field when the clicked automator is allowed to push, so only the clicked prompt runs. Direct or cron runs on a shared field still decline. Entity-dependent scopes need entity_context on the chat input. Enable debug logging to see declined versus push_disabled versus pushed in Recent log messages. The Usage tab only records a successful push. Multi-value fields run one chat call per delta, so context can be selected and billed N times. Use the per-consumer token limit to cap that.

Accessing consumer settings

  1. Go to /admin/config/ai/context/settings/consumers and click Configure context
  2. For an agent, open the agent edit form at /admin/config/ai/tools-automation/agents, expand Context Control Center, and follow the link

The shared editor is at /admin/config/ai/context/settings/consumers/{consumer_id}/edit. Agent IDs use the canonical form agent:{agent_id}. The colon may appear literally or encoded as %3A in a URL; both resolve.

Consumer types

Consumer Types at /admin/config/ai/context/settings/consumer-types lists plugins. Each type has a status column and an Edit form for the type-wide Enable this consumer type flag. There are no inline toggles on the listing. Leftover ai_context.consumer_type_settings.{type} objects whose plugin is gone appear as stale rows. Use Remove configuration for those. That deletes the type settings object only; leftover instance rows stay on Consumers.

Configure consumers opens Consumers with the Type filter set to that type, through ?type={type} (for example /admin/config/ai/context/settings/consumers?type=agent). The operation appears only for types that have rows on Consumers, including stale rows with leftover instances. An unknown type value shows all types.

Disabling the Agent type turns off automatic push for every agent, including agents with no saved override. Pull-based context tools keep working. The listing then shows Off (type disabled). A type that cannot work on this site shows Unavailable on the type listing and Off (type unavailable) on the consumers listing.

See Consumer type API if you are implementing a type.

Configuration options

Push context automatically

Controls whether ranked context is pushed into this consumer. Enabled by default for agents.

When enabled, context is ranked and pushed within the global-item and token limits.

When disabled, automatic push does not run. Scope subscriptions and inclusion overrides still apply to pull-based context tools. GetRelevantAiContextItems and ListAiContextItems inherit the running agent ID when omitted.

See Events for how this interacts with BuildSystemPromptEvent.

Scope subscriptions

Consumers can subscribe to scope values to prioritize matching items. A subscription match is a ranking signal, not a delivery guarantee.

Subscriptions are available for scopes that support them. Some scopes -- like Global, Languages, Roles, and Specific Entities -- do not use subscriptions because they filter or match automatically based on context.

See Scopes and Context Selection. Entity-dependent scopes need the request entity or page path; see Page and entity context.

Always include

Items that should receive priority for this consumer, even when they do not match Languages, Site Sections, Entity Types, Taxonomy Terms, or Roles. They must still be published and visible. The token limit can still shorten or omit them.

Lists are stored as context item UUIDs so they survive configuration export and import. Runtime still accepts leftover numeric IDs.

Never include

Items that must not be used for this consumer, even if another rule would include them. Stored the same way as Always include (UUIDs).

Export and import

ai_context.consumers is configuration, but not every stored reference is portable between environments.

  • Always include and Never include use context item UUIDs.
  • Consumer IDs (agent:my_agent) and subscriptions to Use Cases, Site Sections, Languages, Entity Types, and Roles use machine names or config IDs. Those match on the target site.
  • Subscriptions to Context Tags or Taxonomy Terms store taxonomy term UUIDs. They match after a recipe or Default Content import even when the destination site assigns new serial tids. Term YAML should not set tid.
  • Specific Entities lives on the context item, not in consumer config. Default Content serializes those references as entity: <uuid> through the dynamic entity reference field.

Context items move by UUID through recipes or Default Content. Term-based scope values on those items also use term UUIDs.

See Scopes.

Context limits and selection mode

Optional overrides of the site-wide limits:

  • Max global context items
  • Max tokens
  • Context selection mode

Selection mode is a nested ladder. Hard filters apply in every mode.

  • Site default — follow ai_context.settings:selection_mode. If that setting changes later, this consumer changes with it. This is the first-save radio for most consumer types. Saving it stores inherit on the consumer row.
  • Minimal — global items, always-include, Specific Entities matches, and strict scope subscription matches. This is the first-save radio for Automators.
  • Relevant — Minimal, plus items that Languages, Site Sections, Entity Types, or Taxonomy Terms positively match.
  • Broad — Relevant, plus remaining published context, ordered by Priority, until the token budget is used.

Each consumer type declares its first-save radio. A saved row that omits the key uses that type default. See Consumer type API for how a type declares it.

If there are no scope subscriptions, the editor warns while Minimal is in effect.

Automatic injection never widens a consumer's stored mode. getRenderedContext() and getResult() may pass a mode; that is caller opt-in. See API stability.

Loop-aware context injection

Shown only for the Agent type. When enabled, context is pushed only on loop 0.

See Events.

How context selection works

When a consumer runs, the same pipeline as Context Selection runs. Agent-backed requests without a stored mode use the site-wide default.

Consumers listing

/admin/config/ai/context/settings/consumers lists live instances (agents first, then other types by label), any override rows whose type is unavailable, and any stale override rows. Stale means a saved consumer_id that nothing explains any more: its type plugin is gone, or the type works and the instance was deleted (a config import leftover, for example). Deleting an agent or automator already removes its row. Use Remove configuration for leftovers. A type whose create() throws is omitted from this listing and from routing. Check Recent log messages.

When a consumer type's module is uninstalled

Uninstalling the module behind a consumer type (Automators, for example) is not the same as deleting one automator. Saved overrides survive the uninstall and stay on this listing as Off (type unavailable), with both Configure context and Remove configuration, so the configuration is still there when the module comes back. Deleting a single host entity while its module is still installed removes that row as before.

Only instances with a saved override can be listed this way. An automator that never had context configured leaves nothing behind, so it disappears with its module.

The toolbar above the table has three client-side filters that combine with AND. Search matches the name, description, type text, automatic-push label, and configuration summary (including subscription labels that collapse into +N). Each search word is matched separately, in any order. Put words in double quotes to match them as a phrase. Type lists only the types that have a row on the page, including leftover rows; a leftover row whose type is gone has no label left to show, so it is listed under its machine name. Automatic push offers All, On and Off; Off includes every off variant (Off, Off (type disabled), Off (type unavailable) and Off (stale)). Every change announces the visible count, or that no consumers match.

The table caption is kept for screen readers and is not shown visually. The page title and intro already name the listing.

The Configuration summary column shows count pills (N global, N always included, N never included) and subscription value pills. Count pills stay fully visible. Subscriptions past the first two collapse into a +N pill. A consumer with none of those shows a No configuration pill.