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

Scope subscriptions

Agents can subscribe to specific scope values to prioritize relevant 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".

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

See Scopes for details.

Always include

Specific context items that should always be included when this agent runs, regardless of scope matching or relevance ranking. Use this for critical context that an agent must always have access to (e.g., brand guidelines, compliance rules).

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. Global items still count toward the total max context items limit.
  • Max context items caps how many context 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 matching 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 target-entity 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 max item and token limits.

Assigned items

Manually assign specific context items to an agent. Assigned items are considered during scope scoring and are prioritized over unassigned items that happen to match by scope.

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. Items are filtered by the agent's configuration (never include, always include)
  3. Hard context filters run (language, site section, entity bundle, etc.)
  4. Global items are included up to the configured global item limit
  5. Entity-targeted and entity-bundle-matched items 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. Top-scored items are merged by priority and capped by max items
  8. Subcontext children are resolved for selected parents (when subcontext hierarchy is enabled; children are added after the max items cap)
  9. Items are rendered within the configured max tokens
  10. 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 Services.

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.