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 agents
Go to /admin/config/ai/tools-automation/agents to add one or more AI agents. Agents are
the consumers of context items -- each agent can have its own context
configuration.
Step 2: Create context items
Go to /admin/config/ai/context/items to create context items. Each item contains
information that agents can use when helping with tasks on your site. Content
is written in markdown using the MDXEditor.
Step 3: Configure agent context
Go to /admin/config/ai/context/settings/agents to configure which context items
each agent can access. For each agent you can set:
- Scope subscriptions -- which scope values the agent should prioritize
- Always include -- context items prioritized without scope matching
- Never include -- context items explicitly excluded from the agent
See Agent configuration for full details and Context Selection for how these settings affect filtering and ranking.
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 |
| Context prefix | Text prepended before injected context in agent system 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 selection and rendering details to the ai_context log. See Debugging |
These limits apply to agent 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 agent 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 |
| Agent settings | /admin/config/ai/context/settings/agents |
| Agent context edit | /admin/config/ai/context/settings/agents/{agent_id}/edit |
| 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, agent 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, agents, usage clear | — | — | — | Yes |
Settings, agents, 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, agent 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, agent, usage, and extensions settings
- Per-agent context configuration forms
- 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
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.