The AI Module and Providers

This content was generated with the assistance of AI and should be verified against the official Drupal documentation before being relied on in production.

This sub-section’s Drupal bibliography lists the reference material consulted while preparing these pages.

The AI module (drupal/ai) is the contributed foundation that lets a Drupal site talk to language models and other AI services through one provider-neutral API. It does nothing visible on its own: it defines operation types (chat, embeddings, moderation, text-to-image, speech-to-text and so on), stores which provider and model handle each one, and offers submodules that use those operations, such as AI Automators, a chatbot and a CKEditor integration. Actual services are added by separate provider modules, and their credentials are held by the Key module.

This page was checked on 2026-10-30 against Drupal 11.4.x, PHP 8.3+ and Drush 13/14. The current stable line of the AI module is 1.5 (1.5.2 was released on 2026-10-28, alongside 1.4.11), with 2.0.x in development; AI Agents is being folded into the 2.0 line. Its project page lists compatibility with Drupal ^10.5 || ^11.2, while the module documentation still states ^10.3 || ^11; use the Composer constraint, which is authoritative for what installs. Drupal 10 reaches its end of life on 2026-12-09, so a new AI-enabled site starts on Drupal 11. The running example is the Meridian Museum: the meridian site generates alt text for collection photographs, indexes exhibition content for a visitor chatbot and, in a later page, exposes collection search to an agent through the MCP Server module and AI agents.

The building blocks

flowchart LR F[Feature module<br/>Automators, Chatbot, CKEditor, Canvas AI] --> C[AI core<br/>operation types and defaults] C --> P[Provider module<br/>OpenAI, Anthropic, amazee.ai ...] P --> K[Key module<br/>key entity] K --> E[(Environment variable<br/>or secrets store)] P --> S[External AI service]

  • AI core provides the plugin managers, the ai.provider service, the settings form at /admin/config/ai/settings, external moderation at /admin/config/ai/ai-external-moderation, the AI API Explorer, observability and the events that other modules subscribe to. It ships no provider itself.

  • Provider modules adapt a service (a hosted API, a cloud platform or a local model server) to the operation types it supports. The module documentation lists them in a matrix with 13 operation-type columns (Chat, Vector Database, Embeddings, Moderation, TextToImage, TextToSpeech, SpeechToText, SpeechToSpeech, AudioToAudio, TranslateText, ImageClassification, ImageToImage, ObjectDetection) and a release status. The project describes "95 and counting" connected platforms; built-in integrations include amazee.ai, Anthropic, AWS Bedrock, Azure, Google Gemini, Google Vertex, Hugging Face and OpenAI.

  • Key is the only hard dependency besides a provider. It stores a secret as a configuration entity that points at a key provider describing where the value really lives.

  • Feature modules consume operations without knowing which provider runs them.

The submodule list of the 1.5 line is: AI API Explorer, AI Assistant API, AI Automators, AI CKEditor, AI Chatbot, AI Observability and the provider-related helpers. Several former submodules (AI Search, AI Content Suggestions, AI Translate, AI Validations, AI ECA, AI Logging and Field Widget Actions) are moving to or already live in standalone projects, so check each one’s own project page before depending on it.

Installing the module and a provider

composer require 'drupal/ai:^1.5' 'drupal/key' 'drupal/ai_provider_anthropic'
ddev drush pm:install ai key ai_provider_anthropic
ddev drush cache:rebuild

Source: AI module documentation: installation and setup

Once a provider is configured, the AI module picks a default model for each operation type the provider supports. Review them at /admin/config/ai/settings and override any of them: most feature modules use these defaults but let you choose another provider per use. The same screen has an Advanced Settings section with the HTTP request timeout, 60 seconds by default; raise it for translation and reasoning models, which can run longer.

Provider module names follow ai_provider_<service> (for example ai_provider_anthropic and ai_provider_amazeeio), but the exact name, version and the operation types supported differ, so read the provider’s page in the matrix before requiring it. Providers that have only a pre-release or no release are visible in the matrix as such.

Keeping credentials out of configuration

An API key is a bearer credential: whoever holds it spends the museum’s budget. Two rules apply to every provider.

  1. The provider’s settings form asks for a Key entity, never for the secret itself. Only the key’s machine name ends up in exported provider configuration.

  2. The key entity uses the Environment key provider (or the File provider outside the web root, or an external secrets manager), so the value itself is never written to the database or to config/sync.

The Key module rates its storage options in this order: Configuration (database, intended for development only), File and Environment (better), and External key management (best). Create the key at /admin/config/system/keys or export the entity like any other configuration:

# config/sync/key.key.anthropic_meridian.yml -- contains no secret value
langcode: en
status: true
dependencies: {  }
id: anthropic_meridian
label: 'Anthropic (Meridian)'
description: 'Read from the ANTHROPIC_API_KEY environment variable.'
key_type: authentication
key_type_settings: {  }
key_provider: env
key_provider_settings:
  env_variable: ANTHROPIC_API_KEY
  base64_encoded: false
  strip_line_breaks: true
key_input: none

Source: Key module project page

The env provider reads the named variable at request time, so the DDEV, CI and production environments each define their own value. Locally, DDEV can keep it out of version control:

# stored in .ddev/.env (git-ignored), not in .ddev/config.yaml
ddev dotenv set .ddev/.env.ai --anthropic-api-key=CHANGE_ME
ddev restart

Source: DDEV commands: dotenv set

Pitfalls:

  • Selecting the Configuration key provider in a staging or production site writes the secret into the configuration storage; a later drush config:export places it in the repository. Treat any such key as leaked and rotate it.

  • A key entity whose environment variable is unset resolves to an empty value, and the provider then fails with an authentication error at the first AI call rather than at save time. Add the variable to every environment, including the one that runs drush cron.

  • Keys are per provider and per environment. Use separate keys (and spending limits) for development, staging and production so a leaked development key cannot spend production budget.

  • Provider keys are distinct from consumer subscriptions: for example, an OpenAI or Anthropic API key is not the same thing as a ChatGPT or Claude chat plan.

Older books such as Drupal 10 Development Cookbook (2023) and Drupal 10 Masterclass (2023) predate the AI module and the Drupal CMS AI Assistant entirely; for credentials they can only offer the generic settings.php approach, and the Key module with an environment or external provider is the current practice.

AI Automators

AI Automators generate, amend or evaluate the value of a field from other fields, using a prompt and a provider. They need AI core with a configured provider, the Token module and Field UI. To use one, edit a field on an entity type’s Manage fields tab and enable an automator; the settings include the input mode (basic or advanced with tokens), the base field, the prompt, Edit when changed, a label, a weight and the provider. Automators on the same entity run in weight order, adjustable on the AI Automator Run Order tab.

The worker decides when the value is generated:

  • Direct generates it while the entity saves.

  • Batch runs through JavaScript-driven batching, so it does not trigger on programmatic saves.

  • Queue/Cron defers generation to the next cron run through the ai_automator_field_modifier queue. The batch size is set at /admin/config/ai/ai-automators/settings ("Queue items per cron run": 10 on new installs, 0 meaning all items).

  • Field Widget runs from a button on the edit form through AJAX without saving the entity.

For the museum, a collection_object entity gets a plain-language summary field filled from its material, period and dimensions fields, with the queue worker so that a bulk CSV import is not slowed by model calls. See queue, batch and cron APIs for how cron drains queues.

Automator chains run several steps on a temporary entity that is deleted afterwards and return the output field’s value. Chain types live at /admin/structure/ai/automator_chain_types; custom code starts one with the ai_automator.automate service. Chains are exposed to editors through Field Widget Actions (users need the "Use automator chain widget actions" permission, separate from field edit access) or the AI CKEditor integration. Showing the chain administration pages without those modules needs $settings['ai_automator_advanced_mode_enabled'] = TRUE; in settings.php.

Because the generated text is saved as ordinary field content, review it like any other editorial input. Generated fields are visible to visitors once the entity is published: route automator-filled fields through the moderation workflow so a Reviewer approves them.

Source: AI module documentation: AI Automators

AI Search

AI Search builds on the Search API module (see Search and Search API). It splits content into chunks, converts each chunk to a vector embedding through an embeddings-capable provider, and stores the vectors in a vector database provider. A query is embedded the same way and the nearest chunks are returned, which supports retrieval-augmented generation (RAG): matching content is passed to a chat model so the answer stays grounded in the site.

Setup is: enable the AI Search backend and a vector database provider, create a Search API server using the AI Search backend, create an index over exhibition and event content, index it, and optionally apply the Score Threshold processor. Index each item’s URL so the model can cite correct addresses. The results can be used in a View with a full-text field or by an assistant’s RAG action. The AI Reranker Search API processor, part of AI core, reorders results from Database, Solr or vector backends with a reranking model.

The AI module’s own documentation marks the bundled AI Search as being deprecated in favour of a standalone project, removed from the AI module in 1.6.0. Install AI Search as its own project on new sites and plan the migration on existing ones. Each indexed chunk is sent to the embeddings provider, which has the privacy and cost consequences described below.

Source: AI module documentation: AI Search

AI Assistant API and AI Chatbot

AI Assistant API (experimental, and documented as not recommended for production) normalises conversations between a site and a language model and lets other modules define plugin-based actions that the model can trigger. An assistant is a configuration entity added at /admin/config/ai/ai-assistant with a system prompt (the role), pre-prompt instructions, and an ordered list of actions. Without an action provider such as AI Search or AI Agents the assistant knows nothing about the site. Two settings.php switches control the prompt editing:

// settings.php: allow editing the Pre Action Prompt and per-assistant prompts.
$settings['ai_assistant_advanced_mode_enabled'] = TRUE;
$settings['ai_assistant_custom_prompts'] = TRUE;

Source: AI module documentation: AI Assistant API

AI Chatbot is the front end. Place the AI Chatbot block from /admin/structure/block in a region of the meridian theme (see blocks and block layout), choose a ChatProcessor plugin (the AI Assistant API provides one, and custom plugins can be written), set the initial statement and avatar. Message history is kept in the block until the page reloads or the visitor navigates away. A public chatbot lets anonymous visitors trigger paid model calls: restrict the block’s visibility, require a permission, add rate limits at the edge and set a monthly spending cap at the provider.

Source: AI module documentation: AI Chatbot

The Drupal CMS AI Assistant

Drupal CMS 2.x offers an optional AI Assistant recipe (recipes are covered in Recipes and the distribution in Drupal CMS and site templates). Install it from Extend > Recommended add-ons (/admin/modules/browse/recommended), pick a provider, enter an API key if the provider needs one, and clear the cache. Providers offered are amazee.ai (no key; limited free trial), Anthropic and OpenAI (both paid, with keys from the vendor console). An AI Assistant button then appears in the top toolbar and opens a chat sidebar. Because a recipe has no update path, the recipe only sets things up once; afterwards the configuration is ordinary Drupal configuration that you manage like the rest.

What the recipe enables:

  • Alt text generation. In the media image upload form, the Alternative text section gains a Generate with AI button. The editor reviews and edits the text before saving. For Meridian this is used on collection photographs, where a curator corrects object names and dates. Machine descriptions can be wrong or invent details, so treat them as drafts and keep a human review step for accessibility-critical content.

  • Administration chatbot. The assistant answers "where do I change the site name?" questions with navigation steps, and, when permitted, makes configuration changes: creating content types, fields, taxonomies and views. The Drupal CMS documentation says it works best on tasks with creative freedom and is less reliable where accuracy is critical, so read the summary it gives after each task and inspect the resulting field and taxonomy configuration; export and review it in version control before deploying (see configuration management).

  • Canvas page generation. With the canvas_ai submodule of Canvas enabled (see Canvas visual page building) and a provider that supports function calling configured for all chat operation types at /admin/config/ai/settings, a sparkle icon appears in the Canvas editor. An orchestrator routes the prompt: phrases like "Place" or "Use" go to canvas_page_builder_agent, which positions existing enabled components; "Create" may go to canvas_component_agent, which generates new code components; and canvas_template_builder_agent builds whole page templates. Output is non-deterministic and can reference invalid component identifiers. The context sent can exceed 30,000 tokens, so disable unused components, shorten component descriptions, and choose a model with low input-token prices. Slot restrictions are not enforced, so describe in each component’s usage guidance what a slot should accept.

Source: Drupal CMS: AI tools

Source: Canvas: AI assistant

Older Drupal material treats Layout Builder as the only visual builder and has no concept of AI-assisted editing; Canvas and the Drupal CMS assistant are newer than every listed book.

Cost and privacy considerations

  • Cost. Hosted providers bill per token or per request. Costs come from long prompts (Canvas context, large automator prompts), bulk operations (re-indexing for embeddings, a batch automator over thousands of objects) and public endpoints. Prefer the Queue/Cron worker for bulk work, use cheaper models for embeddings and classification, set budgets and alerts in the provider console, and review usage with the AI Observability submodule.

  • Privacy. Whatever is placed in a prompt, indexed for search or uploaded for alt text leaves the server. Do not send personal data, unpublished or private files, or contract material to a provider without a data-processing agreement; choose a provider region and retention policy deliberately, or a self-hosted/private provider. External moderation at /admin/config/ai/ai-external-moderation can screen content before an operation runs.

  • Access. Grant the AI permissions only to trusted roles (see users, roles and permissions). An assistant that can change configuration acts with the capabilities its tools expose, so keep it for administrators.

  • Reliability. Output is non-deterministic and can be wrong, so keep a human review step and the usual security hardening in place.

  • Security reports. Security fixes for the AI module are supplied for the supported branches listed on its security page, and experimental submodules may not be covered until they are stable; do not enable experimental submodules in production.

For the general engineering background on grounding, guardrails and cost, see RAG systems and AI security.

References