Skip to content

Agent Configuration

Each AI agent can be independently configured to control which context items it receives. This goes beyond simple scope subscriptions -- you can override context selection at the per-agent level.

Accessing agent context settings

There are two ways to reach the agent context configuration:

  1. Go to /admin/config/ai/context/settings/agents and click Edit on an agent
  2. From the agent edit form at /admin/config/ai/tools-automation/agents, expand the Context Control Center section and follow the link

The per-agent edit form is at /admin/config/ai/context/settings/agents/{agent_id}/edit.

Configuration options

Allow context injection

Controls whether push-based context injection happens for this agent at all. Enabled by default.

When enabled (default), context is ranked based on scope subscriptions and other criteria, and the ranked result is injected into the agent's system prompt within the configured global-item and token limits.

When disabled, no context is pushed into the system prompt for this agent -- not global items, not always-include overrides, and not scope-subscribed matches. Use this for agents that should rely entirely on context tools (retrieval) to find relevant context on demand instead of receiving it automatically. Scope subscriptions and inclusion overrides below keep working for that retrieval use even while push injection is disabled, since tool calls that carry the agent's ID still inherit them as defaults.

See Events for how this interacts with BuildSystemPromptEvent.

Scope subscriptions

Agents can subscribe to specific scope values to prioritize applicable context items. For example, an agent working in the Canvas editor might subscribe to the "Working with Canvas" use case scope, while a content writing agent might subscribe to "Working with Text". Canvas-enabled sites require Canvas 1.8.0 or later; see Canvas sites.

A subscription match is a ranking signal, not a delivery guarantee. Explicit inclusion overrides, contextual mismatches, access checks, the global-item limit, and the token budget can still change the final context.

Subscriptions are available for scopes that support them. Some scopes -- like Global and Specific Entities -- do not use subscriptions because they apply automatically based on context.

See Scopes for individual scope behavior and Context Selection for filtering and ranking.

Always include

Specific context items that should receive priority when this agent runs, regardless of ordinary scope subscription scoring and hard context filters. Use this for context that should usually appear for an agent, such as brand guidelines or compliance rules.

Always-include items must still be published and accessible, and Global items are merged before them. The token limit can therefore prevent a later always-include item from reaching the rendered prompt or can shorten its content. Always include does not guarantee complete delivery. Do not rely on it as the only control for compliance-critical instructions.

Never include (excluded items)

Specific context items that should never be included for this agent, even if they would otherwise match by scope or relevance. Use this to prevent irrelevant or conflicting context from reaching a particular agent.

Context limits and selection mode

Agents can optionally override the global context limits:

  • Max global context items caps how many global items can be selected.
  • Max tokens caps how much rendered context can be appended to the prompt.
  • Selection mode controls what happens when the agent has no scope subscriptions.

Agents default to Minimal selection mode. This is the safest default for automatic prompt injection: the agent receives global items, explicitly included items, and context that automatically applies to the current task (such as entity-item matches), but it does not receive a broad set of scoped context items unless subscriptions or overrides say so.

Use Match all only for agents that intentionally need broad recall when no scope subscription narrows the selection. In match-all mode, eligible published context items can be considered up to the agent's token budget.

Loop-aware context injection

In the Advanced fieldset on the per-agent edit form, Loop-aware context injection controls whether context is appended on every agent loop iteration.

When enabled, context is injected only on the first loop iteration (loop 0). On later iterations the system prompt is rebuilt without context items. This reduces token usage but is a trade-off: depending on the LLM, prior conversation messages may still carry context influence, and factual or format-constraint context may not be re-injected when needed.

When disabled (default), context is injected on every loop iteration.

See Events for how this interacts with BuildSystemPromptEvent.

How context selection works

When an agent runs, the context selection pipeline works as follows:

  1. Published context items are loaded in chunks (with scope index prefiltering when subscriptions are present)
  2. Never-include overrides are removed, and published, accessible always-include overrides are loaded separately
  3. Hard context filters run (language, site section, entity type, etc.)
  4. Global items are included up to the configured global item limit
  5. Situation-based matches, such as exact Specific Entities matches, are auto-included when applicable
  6. Remaining candidates are scored by scope subscriptions via AiContextScopeResolver; if there are no subscriptions, the agent's selection mode decides whether remaining candidates are ignored (minimal) or broadly considered (match_all)
  7. Scored candidates are ordered by subscription score, with Priority breaking equal-score ties; match_all candidates are ordered by Priority
  8. Selection groups are merged in fixed order
  9. Subcontext children are resolved for selected parents (when subcontext hierarchy is enabled)
  10. Items are rendered within the configured max tokens
  11. The final context text is appended to the agent's system prompt

Agent-backed requests use selection_mode=minimal by default (global, context-auto, and overrides only when scope subscriptions are empty). See Context Selection for the complete behavior and Services for the request API.

Agents listing

The agents settings page at /admin/config/ai/context/settings/agents lists all configured agents and their current context settings. From here you can configure each agent's context independently.