Skip to content

AI Agent Modes documentation

AI Agent Modes puts a Mode dropdown in front of an AI agent chat, so the person using the assistant can say what kind of job they want done before they start typing.

The Mode dropdown in the Drupal Canvas AI message box toolbar, set to All, let the assistant decide

Picking a mode does not take anything away from the assistant. It adds a short instruction to the request that names the sub-agents the work should be routed to. The assistant keeps every tool it had and is simply pointed in the right direction.

A mode is a configuration entity (ai_agent_mode): a saved subset of one parent agent's sub-agents, with an optional instruction of its own. Because it is configuration, a mode can be exported, shipped in a recipe or module, and moved between sites.

Pages

Page For What it covers
Choosing a mode Anyone using the assistant Where the dropdown is, how to pick a mode, how long the choice lasts, and why the dropdown is sometimes not there
Managing modes Site administrators Creating, editing and deleting modes, every field on the form, the four dropdown placements, and the permission
Speaking and listening Site administrators The microphone and reading replies aloud: both switches, the four microphone placements, the languages, the voice commands, and the per-assistant overrides
Developing with modes Developers The entity shape, shipping modes in config and recipes, the block and the render element, the JSON endpoints, and exactly how the steering is applied
Troubleshooting Everyone The traps that look like bugs and are not

Watch it work

Two short walkthroughs, recorded on a Drupal CMS site:

Using the mode selector, 43 seconds: opening the assistant panel, picking a mode, and the assistant scoped to that job.

Managing modes as an administrator, 48 seconds: the Modes listing, a mode edit form, and the placement setting.

Requirements

  • Drupal 11.
  • The AI and AI Agents modules. Nothing else is required.
  • A parent agent with sub-agents, since a mode is normally a subset of them. A mode can also steer with an instruction alone, without naming any sub-agent.

The chat integrations are optional and switch themselves on when the matching module is present: Drupal Canvas AI for the Canvas AI panel, and AI Chatbot or AI Assistant API for the assistant chat.

Getting started

  1. Install the module.
  2. Go to Configuration > AI > AI Agent Modes (/admin/config/ai/agent-modes) and add your first mode.
  3. Open your assistant and pick the mode from the dropdown before you type.

The module ships no modes of its own. The list your site offers is the list someone created on it, or one that arrived with a recipe.

About this documentation

Written for the 1.0.x branch, verified against release 1.0.0-alpha2.