Skip to content

Drupal AI Architecture Guidelines

Direct Answer

Build on Drupal 11.4.6; use Drupal CMS 2.1.4 as a recipe-based starting point, not an ongoing distribution dependency. Use stable Drupal AI, AI Agents, ECA, Search API, and Key before writing custom integrations. Treat Tool API, AI Search, MCP Client, MCP Tools, and MCPIO as controlled pilots because their current releases are beta/alpha or lack security coverage.

Current Drupal Baseline

Component Recommended baseline
Drupal core 11.4.6
Drupal CMS 2.1.4; apply its recipes, then manage the resulting Drupal site normally
PHP 8.3–8.5 for Drupal 11.4
Composer 2.7+
Drush Drush 14 for Drupal 11.3+
Database MySQL 8+, MariaDB 10.6+, PostgreSQL 16+ with pg_trgm, or SQLite 3.45+
Capability Project Evidence Compatibility Caveat
Provider abstraction, guardrails, automators AI 1.4.8 Stable, security-covered; 18,000+ reported sites Drupal ^10.5 or ^11.2 Prefer stable 1.4 over 1.5 RC
Drupal-native agents AI Agents 1.3.5 Stable, security-covered; 10,000+ sites Drupal ^10.3 or ^11 Restrict tools and permissions
Deterministic automation ECA 3.1.8 Stable, security-covered; config-deployable models Drupal ^11.3 Use ECA Queue for asynchronous work
Conventional search Search API 1.41 Stable, security-covered; 163,000+ sites Drupal ^10.3 or ^11 Start here before vector search
Secrets Key 1.22 Stable, security-covered Drupal 9–11 Use an external provider; never exported config
Translation AI Translate 1.4.2 Stable, security-covered Drupal ^10.4 or ^11 Keep generated translations in draft moderation
Semantic search/RAG AI Search 2.0 alpha Search API integration and multiple VDBs Drupal ^10.4 or ^11 No supported stable release
Reusable callable operations Tool API beta8 Typed inputs/outputs and JSON Schema Drupal ^10.5 or ^11 Security policy applies, but no stable release
External agent access MCP Client / MCP Tools / MCPIO Emerging Tool API integrations Drupal 10/11 Alpha/beta; some lack security coverage

Contrib-First Architecture

Drupal CMS recipes → Core entities, workflows, moderation, queues and access control → AI + stable provider + externally backed Key → AI Agents for bounded reasoning → ECA for deterministic orchestration → Search API → optional AI Search/VDB pilot → Tool API/MCP only behind narrow permissions and staging gates.

Write custom code only for a missing Tool plugin, provider adapter, access policy, or domain-specific service. Keep recipes responsible for composition.

AI-Agent Delivery Workflow

  • Inspect core and contrib before generating code.
  • Add dependencies with Composer in an isolated worktree.
  • Compose modules through recipes and exported configuration.
  • Give agents least-privilege tools; require human approval for publishing, configuration mutation, deletion, and deployment.
  • Test with PHPUnit, Kernel, Functional, FunctionalJavascript, config-import, update-path, PHPStan, coding standards, and Composer audit.
  • Deliver through MR, CI, staging config import, queue execution, moderation review, and production smoke tests.

Risks and Open Questions

  • MCP and vector-search projects are moving quickly but are not all production-stable.
  • Long-running work should leave HTTP requests and use Queue API/ECA Queue or an external worker.
  • Prompt injection must never bypass Drupal access checks, moderation, validation, or tool-level schemas.
  • Provider retention, data residency, cost ceilings, observability, and rollback policy require explicit decisions.

Takeaways

  • Use stable Drupal AI, AI Agents, ECA, Search API, and Key as the production foundation.
  • Keep experimental Tool API/MCP/RAG capabilities isolated and permission-constrained.
  • Let agents assemble recipes and propose changes; let Drupal permissions, humans, CI, and deployment policy authorize mutations.