Configuration
Admin navigation
Find Context Control Center at Configuration → AI → Tools & Automation → Context Control Center.
After enabling the module, follow these steps to configure AI Context.
Step 1: Create consumers
Go to /admin/config/ai/tools-automation/agents to add one or more AI
agents. AI Context ships the Agent and Automator types. Automator
instances appear when AI Automators is installed. Other integrations
(for example AI CKEditor) appear here when those projects ship a
consumer type.
Each live instance can have its own override in ai_context.consumers.
Step 2: Create context items
Go to /admin/config/ai/context/items to create context items. Each item contains
information that consumers can use when helping with tasks on your site. Content
is written in markdown using the MDXEditor.
Step 3: Configure consumer context
Go to /admin/config/ai/context/settings/consumers to configure which
context items each consumer can access. For each instance you can set:
- Push context automatically -- whether ranked context is pushed
- Scope subscriptions -- which scope values the consumer should prioritize
- Always include -- context items prioritized without scope matching
- Never include -- context items explicitly excluded from the consumer
See Consumer configuration for full details and Context Selection for how these settings affect filtering and ranking.
Consumer Types at
/admin/config/ai/context/settings/consumer-types lists plugins. Each
type has an Edit form for the type-wide Enable this consumer
type flag. Disabling the Agent type turns off automatic push for
every agent, including agents with no saved override. Leftover type
settings whose plugin is gone appear as stale rows with Remove
configuration.
Overview page
The CCC overview dashboard, Show overview page setting, and behavior when disabled are documented in Overview page.
General settings
Configure module-wide defaults at /admin/config/ai/context/settings/general:
| Setting | Description |
|---|---|
| Show overview page | When enabled, /admin/config/ai/context/overview is the CCC default landing page. See Overview |
| AI Provider/Model | Provider and model for conditional subcontext AI decisions (when Enable conditional subcontext AI decisions is on under Context item settings) and for local token estimation when trimming injected context to the token budget. Select - None - to clear. The field description shows whether conditional subcontext AI decisions are currently enabled or disabled |
| Max global context items | Cap on global items included per selection (default: 3) |
| Max tokens for injection | Token budget for rendered context appended to prompts (default: 1200). Any selected item, including Always include and required subcontext items, may be shortened or omitted |
| Default context selection mode | Site-wide default for how much published context is considered (minimal, relevant, or broad; default: relevant). Applies to every consumer that does not set its own mode; consumers can override it per instance. Direct AiContextSelection construction must specify the desired mode. See Context Selection |
| Context prefix | Text prepended before injected context in agent and generic chat prompts. Default: "The following site-specific context applies to this task. Use it strictly when relevant; do not override user intent." Translatable via Configuration translation |
| Enable debug logging | Writes consumer routing, selection, and rendering details to the ai_context log. See Debugging |
These limits apply to consumer injection unless overridden per request (for example via function call parameters or programmatic API calls).
Clearing the provider: Select - None - when no enabled feature requires a provider. You cannot clear the provider while conditional subcontext AI decisions are enabled and published conditional subcontext items exist — change those items to required, remove their parent, or disable conditional AI decisions on Context item settings first.
When conditional AI decisions are disabled, conditional children are excluded from normal context selection. The provider may remain configured for injection token estimation or future use.
Context item settings
Configure publishing defaults and subcontext behavior at
/admin/config/ai/context/settings/items:
| Setting | Description |
|---|---|
| Publish by default | New context items default to published (default_status) |
| Create new revisions by default | New edits create a revision by default (new_revision) |
| Enable subcontext hierarchy | Master toggle for parent/child context items. When disabled, subcontext resolution is skipped and saving an item clears subcontext fields |
| Enable conditional subcontext AI decisions | When enabled, an AI call decides which conditional children to include per parent. Missing or unsupported providers, exhausted decision caps, invalid responses, and provider exceptions exclude conditional children while preserving required children. When disabled, conditional children are excluded from normal context selection (required children are still included; conditional children may still appear via agent Always include, custom scope, or similar paths) |
| Max conditional parent decisions per request | Caps provider calls per context resolution (default: 3, range: 1–20). One call per parent under the cap; parents over the cap or failed AI calls fall back to required children only for that parent. Which parents receive a decision when the cap is hit follows internal processing order, not task relevance |
Conditional subcontext uses one provider call per parent (not batched across parents), with per-request caching for identical decisions. See Subcontext hierarchies.
When Scheduler is installed, this page also links to Scheduler's no-bundle
settings form for the ai_context_item entity type. See
Scheduling.
Settings deep links
General settings and context item settings forms support a ?fieldset=
query parameter that opens the matching details fieldset on load and
scrolls it into view.
| Form | Example |
|---|---|
| Context item settings | /admin/config/ai/context/settings/items?fieldset=subcontext |
| General settings | /admin/config/ai/context/settings/general?fieldset=debugging |
Fieldset keys match the form element keys (subcontext, publishing,
scheduling, context_injection, debugging, and so on).
Configuration translation
The Context prefix setting (context_prefix in ai_context.settings) is
translatable via Drupal's Configuration translation UI
(/admin/config/regional/config-translation → AI Context settings).
This lets multilingual sites inject a localized prefix before context blocks
in consumer system prompts.
Admin pages reference
Context management
| Page | Path |
|---|---|
| Overview | /admin/config/ai/context/overview |
| Context items | /admin/config/ai/context/items |
| Add context item | /admin/config/ai/context/items/add |
| Usage | /admin/config/ai/context/usage |
Settings
| Page | Path |
|---|---|
| Settings (redirects to General) | /admin/config/ai/context/settings |
| General settings | /admin/config/ai/context/settings/general |
| Context item settings | /admin/config/ai/context/settings/items |
| Scope settings | /admin/config/ai/context/settings/scope |
| Consumer settings | /admin/config/ai/context/settings/consumers |
| Consumer context edit | /admin/config/ai/context/settings/consumers/{consumer_id}/edit |
| Consumer types | /admin/config/ai/context/settings/consumer-types |
| Consumer type settings | /admin/config/ai/context/settings/consumer-types/{type} (underscores in the type ID become hyphens) |
| Usage settings | /admin/config/ai/context/settings/usage |
| Clear usage records | /admin/config/ai/context/settings/usage/clear |
Entity routes
| Page | Path |
|---|---|
| View context item | /admin/config/ai/context/items/{id} |
| Edit context item | /admin/config/ai/context/items/{id}/edit |
| Delete context item | /admin/config/ai/context/items/{id}/delete |
| Duplicate context item | /admin/config/ai/context/items/{id}/duplicate |
| Revision history | /admin/config/ai/context/items/{id}/revisions |
| View revision | /admin/config/ai/context/items/{id}/revisions/{rev}/view |
| Revert revision | /admin/config/ai/context/items/{id}/revisions/{rev}/revert |
| Delete revision | /admin/config/ai/context/items/{id}/revisions/{rev}/delete |
| Usage record detail | /admin/config/ai/context/usage/{usage_id} |
Permissions
Grant permissions at /admin/people/permissions/module/ai_context. The
module defines 15 permissions in ai_context.permissions.yml. Content
Moderation also generates workflow transition permissions for the
ai_context_editorial workflow; those are not listed in that file.
These two permissions serve different purposes:
- View AI Context Items in CCC (
view ai context items) - Use Published AI Context in AI Features (
access published ai context)
For how context item, usage, and target-entity checks interact (including redaction on usage pages), see Access boundaries.
Trust model
Roles that can create, edit, publish, or administer context items are
trusted with prompt-level influence. Published context (especially global
items) can be injected verbatim into AI agent system prompts for other users.
Authoring permissions are marked restrict access: true for that reason.
Who can receive published context is separate. Selection and context tools
honor the current user's entity view access. The lighter
access published ai context permission covers AI consumption and canonical
view of published items, not CCC listing or settings administration.
Consumer access vs CCC editorial access
| Capability | Use Published AI Context in AI Features | View AI Context Items in CCC |
|---|---|---|
| Machine name | access published ai context |
view ai context items |
| Published context in AI selection and context tools | Yes | Yes |
| Canonical view of a published item | Yes | Yes |
Context items listing (/admin/config/ai/context/items) |
No | Yes |
| Overview dashboard and editorial CCC navigation | No | Yes (or create/administer) |
| View others' unpublished items | No | No (needs view any unpublished …) |
| Create, edit, delete, or administer items | No | No (needs entity permissions) |
A role with only create ai context item can reach the add form and CCC
entry routes that accept create permission, but cannot open the context
items listing without view ai context items.
Separating end-user consumption from CCC UI access more strictly is planned for 1.1 (#3586357).
Recommended role bundles
These bundles reflect the access rules covered by automated access tests. Adjust for your site; they are guidance, not install-time defaults.
Published-context consumer
For authenticated users who should receive published context in AI features but do not manage CCC content.
| Permission | Purpose |
|---|---|
Use Published AI Context in AI Features (access published ai context) |
Use published context in AI selection/tools; view published items the user can access |
Does not grant the context items listing, settings, usage pages, or authoring.
Context author
For users who create and maintain their own context items.
| Permission | Purpose |
|---|---|
View AI Context Items in CCC (view ai context items) |
Listing and editorial CCC navigation; view own unpublished items |
create ai context item |
Create new items |
edit own ai context item |
Edit own items |
delete own ai context item |
Delete own items |
use ai_context_editorial transition create_new_draft |
Save drafts and create new draft revisions |
use ai_context_editorial transition publish |
Publish own items |
Authors see their own unpublished items via ownership combined with
view ai context items. They cannot view, edit, or delete items owned by
others without additional permissions.
Context editor
For editorial staff who manage context across authors. Includes the author bundle, then adds:
| Permission | Purpose |
|---|---|
view any unpublished ai context item |
View unpublished items regardless of author |
edit any ai context item |
Edit any item |
delete any ai context item |
Delete any item |
view all ai context item revisions |
Revision history (requires entity view access) |
revert all ai context item revisions |
Revert revisions (requires edit access) |
delete all ai context item revisions |
Delete revisions (requires delete access) |
use ai_context_editorial transition archive |
Archive draft or published items |
use ai_context_editorial transition restore_to_draft |
Restore archived items to draft |
use ai_context_editorial transition restore |
Restore archived items to published |
When Scheduler is enabled, editors who schedule context items typically also need:
| Permission | Purpose |
|---|---|
schedule publishing of ai context items |
Schedule future publish/unpublish |
view scheduled ai context item |
View scheduled items in Scheduler UI |
Revision permissions apply only to items the user can already view. An editor
with view all ai context item revisions but without access to another
author's unpublished item cannot open that item's revision history.
Context administrator
For site builders who configure CCC module-wide behavior. The recommended bundle includes the editor bundle, plus:
| Permission | Purpose |
|---|---|
administer ai context |
All settings routes, consumer context configuration, usage clear, and bypass of entity access checks |
view ai context usage |
Usage listing and record detail pages |
administer ai context bypasses entity view, update, and delete checks, but
it does not grant the context items listing route or replace workflow
transition permissions. Listing still requires view ai context items.
Moderated saves still require the appropriate
use ai_context_editorial transition * permissions from the editor bundle.
Role capability matrix
The Administrator column assumes the recommended bundle above: editor
permissions plus administer ai context and view ai context usage.
| Capability | Consumer | Author | Editor | Administrator |
|---|---|---|---|---|
| AI selection / context tools (published) | Yes | Yes | Yes | Yes |
| Context items listing | — | Yes | Yes | Yes |
| View own unpublished items | — | Yes | Yes | Yes |
| View any unpublished items | — | — | Yes | Yes |
| Create items | — | Yes | Yes | Yes |
| Edit/delete own items | — | Yes | Yes | Yes |
| Edit/delete any items | — | — | Yes | Yes |
| Revision management (any) | — | — | Yes | Yes |
| Usage listing / records | — | — | Optional | Yes |
| Settings, consumers, usage clear | — | — | — | Yes |
Settings, consumers, and usage clear require only administer ai context. The
other Administrator cells depend on the editor permissions listed above.
Module permissions reference
Quick lookup for all 15 permissions in ai_context.permissions.yml:
| Permission | Summary |
|---|---|
administer ai context |
Settings, consumer context configuration, usage clear; bypasses entity access |
view ai context items |
View AI Context Items in CCC — listing and view access for items the user may see (own unpublished via ownership) |
view any unpublished ai context item |
View unpublished items regardless of author |
create ai context item |
Create new context items |
edit own ai context item |
Edit items authored by the user |
edit any ai context item |
Edit any context item |
delete own ai context item |
Delete items authored by the user |
delete any ai context item |
Delete any context item |
view all ai context item revisions |
Revision history when the user can view the item |
revert all ai context item revisions |
Revert revisions when the user can edit the item |
delete all ai context item revisions |
Delete revisions when the user can delete the item |
schedule publishing of ai context items |
Scheduler publish/unpublish scheduling |
view scheduled ai context item |
View scheduled items in Scheduler UI |
access published ai context |
Use Published AI Context in AI Features — published context in AI features; canonical view of published items; not the listing |
view ai context usage |
Usage listing and individual usage record pages |
Editorial workflow transition permissions
Context items use the module-owned ai_context_editorial workflow. Content
Moderation exposes one permission per transition:
| Transition permission | Workflow action |
|---|---|
use ai_context_editorial transition create_new_draft |
Save as draft; create new draft from published |
use ai_context_editorial transition publish |
Publish draft or published item |
use ai_context_editorial transition archive |
Archive draft or published item |
use ai_context_editorial transition restore_to_draft |
Restore archived item to draft |
use ai_context_editorial transition restore |
Restore archived item to published |
Without the transition permission for the current moderation state, a user
cannot save edits even when they hold edit own ai context item or
edit any ai context item. See Content moderation
for workflow states and upgrade notes.
Administrative routes
These capabilities require administer ai context:
- General, context item, scope, consumer, usage, and extensions settings
- Per-consumer context configuration forms and consumer type settings
- Clear usage records confirmation form
These require view ai context usage (listing also respects per-record
redaction when the viewer lacks access to linked context items or target
entities):
- Usage listing (
/admin/config/ai/context/usage) - Individual usage record pages (
/admin/config/ai/context/usage/{id})
Upgrading
Post-update 0006: stale scope values
Post-update 0006 scrubs leftover dynamic scope values that are no
longer valid options (deleted bundles, terms, languages, roles, removed
Entity Types settings, and removed site sections). After upgrading, run:
drush updatedb -y
drush cr
Standard pipelines run database updates before config import. 0006
scrubs against the environment as it exists then, so a copied
production database on a lower environment can lose values for options
the imminent import is about to add (for example a language or content
type present in config but not yet installed there). On production,
active config is already authoritative. Live cleanup then keeps
storage in sync. Use Case values are not changed.
Update 10026: scope field storage
Update 10026 replaces the serialized scope map blob with a multi-value
ai_context_scope field (scope_id + value). Run it in the same
release window as the new code; do not serve traffic after deploying the
code until drush updatedb finishes this hook. JSON:API output for
scope changes from one nested map to a list of pairs.
drush updatedb -y
drush cr
The update is batched. It dumps existing blobs (including revisions),
rejects corrupt or oversized values before removing the old column, then
installs the new field and rebuilds the scope index. If it throws an
UpdateException, the map column is still in place: repair or delete the
reported row and run drush updatedb again.
Updates 10004, 10006, 10007, and 10011 run before this
conversion when a site jumps from an early beta to current code.
10004, 10006, and 10011 read stored scope from SQL (the old
serialized column, or the new tables if 10026 already ran) and do not
load context items through the Entity API. 10007 updates text-field
displays through the Config API so saving them does not instantiate the
removed ai_context_map formatter.
See Storing scope values for the Default Content / recipe YAML shape.
Update 10023: stored token counts
Update 10023 adds the token_count field on ai_context_item and
backfills stored estimates for existing items. After upgrading to a release
that includes this update, run:
drush updatedb -y
drush cr
The update aborts with an UpdateException if the field cannot be installed,
so the recorded schema version never advances past a missing column. If the
update fails, fix the reported cause (usually a stale entity definition cache)
and run drush updatedb again — the update is idempotent.
Diagnosing a stalled backfill
Token badges on the context listing stay at 0 when the column exists but
counts were never written. Check both:
drush php:eval "echo \Drupal::keyValue('system.schema')->get('ai_context');"
drush sql:query "SHOW COLUMNS FROM ai_context_item_field_data LIKE 'token_count'"
If the column exists and counts are still 0, re-run the backfill without
re-running the field install:
drush php:eval "\Drupal::service('ai_context.token_count_backfill_scheduler')->backfillAll();"
The backfill writes only the token_count column of the revision it read,
so it never overwrites concurrent editorial changes. Items saved with a newer
revision mid-run keep their own count, which preSave() has already
recalculated.
Recounting after a model change
Stored token_count values are estimates for listing badges and budget
summaries, not exact billing.
A recount of stored estimates runs when the resolved tokenizer model changes, from either of:
- The provider/model on General settings (a specific model, or switching CCC onto or off the site chat default when that changes the model name CCC uses).
- The site-wide chat default on the AI module settings page, when CCC is set to use that default.
New item saves and live injection trimming always use the current resolved model. When a recount does run:
| Context | Mechanism |
|---|---|
| CLI (Drush config set, config import, scripts) | Runs synchronously before the command returns |
| General settings form save | Batch, with a progress bar |
| Any other web request (programmatic config save, config import over the UI, AI settings save) | Queued on ai_context_token_count_backfill, drained by cron |
Queued recounts are also drained by the batch when one runs in the same
request, so a form save never leaves work for cron. If counts look stale
on a site with cron disabled, run the backfill manually with the
backfillAll() snippet above.
Update 10028: consumer configuration
Update 10028 copies ai_context.agents rows to
ai_context.consumers and deletes the old object:
- Top-level
agents→consumers - Row
id→ canonicalconsumer_id(agent:{id}) - Added
type loop_aware→settings.loop_awareallow_context_injection→push_enabled
Conflicting rows abort with UpdateException. After upgrading, run:
drush updatedb -y
drush cr
Then re-export site configuration so the sync directory contains
ai_context.consumers instead of ai_context.agents. Importing leftover
ai_context.agents after migration is a validation error.
Recipes or ConfigActions that still write ai_context.agents recreate
an object nothing reads. Update them to ai_context.consumers with
canonical IDs. See
API stability — Beta upgrade: consumer configuration.
Updates 10029–10031: usage consumer fields
These updates replace usage agent_id with consumer_id and
consumer_type, make runner_id optional, backfill
agent:{old_agent_id}, then drop agent_id and repair
views.view.ai_context_usage. A view that only differs by Views
cache metadata, module dependencies, or exposed remember_roles
export keys is treated as the shipped default and replaced
wholesale. A truly customized view is remapped in place and logged
for review. Run these updates in the same drush updatedb as the
new code. A usage table that is missing required columns and still
has rows still fails 10005 with an UpdateException telling
administrators to empty the table first; that behavior is unchanged.