Skip to content

Architecture

This section provides a developer-oriented overview of the AI Context module's architecture.

Entities

The module defines three entity types:

ai_context_item (content entity)

The primary entity. Stores context text (markdown), scope values, target entity references, parent-child relationships, and moderation state. Extends EditorialContentEntityBase with translation and revision support.

  • Bundle entity: ai_context_item_type (config entity, default bundle: default)
  • Base table: ai_context_item
  • Data table: ai_context_item_field_data
  • Revision tables: ai_context_item_revision, ai_context_item_field_revision

ai_context_item_type (config entity)

Bundle definition for context items. Carries Scheduler third-party settings.

ai_context_usage (content entity)

Stores usage tracking records -- which context items were selected, by which agent, on which route, and which tools/entities were involved.

Plugin system

AiContextScope plugins

The scope system is built on Drupal's plugin API. Scope plugins define categories/dimensions for context items. See Scope API.

AiFunctionCall plugin

The module provides one function call plugin (ai_context:get_relevant_ai_context_items) that agents can invoke as a tool. See Function calls.

Services

The module registers 17 services covering scope management, context selection, rendering, usage tracking, event handling, and routing. See Services for the full reference.

Event subscribers

Two event subscribers integrate with the AI Agents module:

  • SystemPromptSubscriber -- appends selected context to agent system prompts
  • AiContextAgentToolSubscriber -- tracks entity modifications by agent tools

See Events.

Hooks

The module implements several hooks and provides one alter hook for extending scope values. See Hooks.

Key data flows

Context selection pipeline

  1. SystemPromptSubscriber listens for BuildSystemPromptEvent
  2. Calls AiContextSelector::select() with the prompt and agent ID
  3. AiContextSelector loads all published items, filters by agent config
  4. AiContextScopeMatcher scores items against agent scope subscriptions
  5. AiContextRouter ranks items by relevance (keyword or LLM strategy)
  6. AiContextRenderer renders items within the token budget
  7. Final text is appended to the agent's system prompt

Usage tracking pipeline

  1. SystemPromptSubscriber captures the runner ID on AgentStartedExecutionEvent
  2. After context selection, records usage via AiContextUsageTracker
  3. AiContextAgentToolSubscriber listens for AgentToolFinishedExecutionEvent and records tool usage and entity modifications