Drupal Canvas is changing how websites are built inside Drupal by bringing design, content, and intelligence into one space. It introduces a visual editor that works in real time, supports React-based components, and understands what you want to build through conversational input.
Instead of writing code or manually assembling layouts, you can describe what you need. Ask for a “homepage with a hero section, a product grid, and a contact form,” and Canvas knows how to put those pieces together. It can also create components, suggest titles, and generate metadata, all within the same interface.
Behind this simplicity is a system of AI agents that collaborate to interpret prompts, choose the right components, and build structured pages. This article explores how these agents work, how they communicate with Drupal, and what makes Canvas a more fluid and efficient way to design and manage content.
Understanding AI agents
Before diving into Canvas AI specifically, we need to understand what AI agents are. Let's first understand the basic problem the AI agents are trying to solve. Imagine you ask a basic LLM, "Add a chocolate ice cream recipe to my site."
The LLM will happily give you a perfectly good recipe. But it's just plain text. You still have to manually copy that text, log into Drupal, create a new 'Recipe' content type (if it even exists), paste the title, paste the ingredients, and so on. It's a hassle.
So, we get smarter. We tell the LLM, "Give me the recipe in a structured JSON format."
This is better! Now we have clean, structured data. But it still requires a developer to write code that can parse this JSON and create a node in Drupal.
An AI agent is essentially an LLM that's been given instructions and tools, allowing it to autonomously decide how to act to complete a task. The keyword here is autonomously. You tell it what you want, and it figures out which tools to use and in what order. Here's what makes agents special:
- They have a system prompt that guides their behaviour.
- They have access to specific tools they can use.
- They operate in a loop, meaning they can use tools multiple times.
- They keep going until the task is actually completed.
A 'tool' is essentially a backend plugin that the AI can call. So when the user says, "Add the recipe," the AI Agent understands the intent. It doesn't just return text. It thinks, 'Aha, the user wants to create a recipe. I have a tool for that called add_recipe.' It then calls that tool with the right arguments (the title and instructions). The Drupal backend executes the tool, a new recipe node is created, and the AI can then report back, "Done! I've added the recipe to your site."
In Drupal, AI agents can be created from the UI itself using the ‘AI agents’ module. Refer to my previous blog to understand more about AI agents. AI features in Canvas are built using AI agents.
Installation and setup
AI features are integrated into their own module, canvas_ai, which comes as a sub-module of Canvas. To set it up:
- Download and install the Drupal Canvas module
- Install Canvas AI module
- Additionally, set up an AI provider that supports tool calling. The complete list of Providers can be found here.
Once done, click on the AI panel icon to launch the chatbot.
AI agents in Canvas AI
Canvas AI isn't just one large agent doing everything. It's actually an orchestrator pattern with multiple specialised agents, each handling the specific tasks you're asking for. These sub-agents are:
- Component Generation Agent
- Title Generation Agent
- Metadata Generation Agent
- Page Builder Agent
- Template Generation Agent
.webp)
Each of these agents has its own set of tools that let it do its job. Let's look at what each one does.
Drupal Canvas component Agent
One of the standout features in Drupal Canvas is the ability to create React components directly from the UI. It's an awesome feature that lets even people with no prior Drupal knowledge create components in Drupal Canvas. This agent lets you create code components directly using natural language. You just describe what you want in plain English, like "create a testimonial card with an image, name, title, and quote," and the agent figures out the rest. It is also possible to generate a component by uploading an image.
The main tools used by the component agent are
Create new component: To create code components
- Arguments: Component name, JS code, CSS code, Props data
Edit JavaScript on components: To edit a code component
- Arguments: Component name, JS, Props data
Get JS Component: Get the code of a component
- Arguments: Component name
The following is a sample of how the agent uses the Create new component tool when asked to create a CTA component.
Watch this video to see a demo of the code component agent
Drupal Canvas title generation Agent & Drupal Canvas metadata generation Agent
These agents specialise in adding SEO-focused titles and metadata (descriptions) to the page based on the added content. Both agents work only with the canvas_page entity type, a content entity shipped with Drupal Canvas and tailored specifically for it. The following is an overview of the tools used by these agents:
Here is a demo of title and metadata generation in action.
Drupal Canvas page builder Agent
This is where it gets really powerful for content editors. The Page Builder Agent is for creating individual sections of a page. Instead of dragging and dropping components, you can just tell the AI what you want. You can give specific prompts like 'Add a hero banner followed by three paragraph components for a blog about climate change,' which the agent will pick up and add to the page, or generic prompts like 'Create a today's specials section for a bakery website.'
It has been observed that with certain models, the Orchestrator Agent might fail to delegate page-building tasks to the Page Builder Agent. Therefore, it's better to prepend all page-building-related prompts with the text, 'Using page builder tool.' For example: 'Using the page builder tool, create a today's specials section for a bakery website.'
Once components are added to the page, you can click on a component and ask the agent to add new components above, below, or into the slots of the selected component. The Page Builder Agent will understand the selected component and add new components relative to it.
For example, assuming you have two-column and heading components and the two-column layout has been added to the page, you can click on it and ask the agent to do the following tasks:
- Using the page builder tool, add a heading with the text 'Hello world' above and below this component. (The agent understands that 'this' refers to the clicked component).
- Using the page builder tool, add a heading with the text 'Hello world' to each slot of this component.
The Page Builder has a more sophisticated set of tools because it needs to understand the existing page state before adding anything. The main tools used are:
- get_current_layout: This tool returns the current structure of the page, including what components are placed where, so it knows what's already on the page.
- get_component_context: The agent uses this tool to retrieve information about all the components available in your site, including SDCs, Code components, and Blocks. The agent uses this to decide which components best fit what you're asking for.
- get_page_data: Used to get the current title and metadata of the page. If the title and metadata are empty when the Page Builder Agent is invoked, it will add an appropriate title and metadata.
- canvas_metadata_generation_agent and canvas_title_generation_agent: If the Page Builder notices your page doesn't have a title or metadata, it can invoke these agents to add them while building the section.
- set_component_structure: This is the tool that actually does the work. After the agent has figured out what components to use and how to arrange them, this tool places them on the page in the right positions with the correct configuration.
This is how the agent passes the component structure to the set_component_structure tool.
The operations array consists of individual operations. Each operation corresponds to a component assembly at a specific area of the page. The first operation should be read as: 'Place the heading component above the component with UUID 7238-xxxx-xxxx in the content region.' The agent uses the 'inside' placement, as seen in the third operation, to add components to an empty region or empty slot.
Watch this video to see the page builder in action
Drupal Canvas template builder Agent
At the time of writing this blog, the Template Builder Agent is not yet merged into the main module. If you want to try it out, you can pull the merge request from this issue. If the Page Builder is about sections, the Template Builder is about entire pages. This agent creates complete page layouts from top to bottom. By default, it generates the main content area, that is, everything between your header and footer. But if you explicitly ask for it, the agent can also create headers and a footer.
The Template Builder uses all the tools used by the Page Builder except set_component_structure, such as get_current_layout, get_component_context, get_page_data, canvas_metadata_generation_agent, and canvas_title_generation_agent. Additionally, it uses the set_template_data tool to generate the template structure and add it to the page.
This is how the agent generates the template structure and passes it to the set_template_data tool.
Each top-level key corresponds to a region in your theme. By default, Drupal Canvas only supports the 'content' region, which is where all the page content will be placed. This region is specific to each page you create in Canvas. Components added to the content region of a page won't appear when you create or edit another page.
It is also possible to enable other regions in your theme in Drupal Canvas. This can be done from your theme's settings page (e.g., for Olivero: /admin/appearance/settings/olivero).
Select the 'Use Drupal Canvas for page templates in this theme.' option and choose the regions you want to enable.
Beware that these additional regions are 'global regions.' Any components added to these regions will be visible across all pages. The template builder can add components to global regions as well. For example, when you ask the agent to generate a template for a library website with a proper header and footer, it checks the available regions to see if there are dedicated header and footer regions, and if present, it will add the components for building the header to the header region and the footer to the footer region. If dedicated regions are not present, it will add all components to the content region.
A dedicated configuration form is available in Configuration -> AI -> Canvas AI Theme Region Settings to give proper instructions to the agent on how to use each of the regions. This is particularly useful when you have regions like 'Footer top' and 'Footer bottom' instead of a single footer region. In that case, you can use this form to inform the agent about what to add in each of these regions. For example, you can add a description like 'Add Site name, logo, and menu links (Using button components) to this region' for the 'Footer top' region and 'Add social media links and copywriting text in this region' for the 'Footer bottom' region. These kinds of descriptions are critical for the agent to generate a reliable template.
How Does the AI Know What Components to Use?
Both the page builder and template builder rely on components present on your site for generating output. Here's something really important to understand: These agents can't actually see your components. They don't know what a component looks like visually. They only understand components through their metadata: props, slots, and descriptions. This means you need to provide good descriptions for your components. There's a configuration form at Configuration -> AI -> Canvas AI Component Description Settings where you can add metadata for Blocks, SDCs, and JavaScript components.
You should include things like:
- How to use the component (Standalone or within the slot of another component)
- When to use it
- What components work well in its slots (can it contain buttons, cards, images?)
- What the props do (How the component behaves for different prop combinations?)
This metadata becomes the context the agent uses to make decisions. If your hero component description says "use this for the top section of a page to grab attention," the agent knows to use it when you ask for a hero section. If the hero component contains a title and image prop, those are self-sufficient, and you don't need to give any extra description for those props. But if there is a design or variation prop that completely changes the design of the component, you should give content around when to use each of those values. For example: Variation one renders an image and title side-by-side, so keep the title character length to 60 characters max. Variation 2 renders the image below the title, so give it a big title. Variation 3 changes the title colour to white, so use it only when the hero banner is placed in a container component with a theme prop value set to 'dark,' etc. If you don't provide these descriptions, the agent might not use the component properly.
The downside? More components mean longer context, which means more tokens are being used, and the costs are higher. It can also reduce output quality if the context gets too large and the agent gets confused by too many options. So make sure the metadata you are adding is optimal.
If no metadata is given from this form, the agent will use the default descriptions available from the component.yml files of SDCs. For JavaScript components and blocks, the agent would just see the name of the component, its props, and its slots. The purpose of the component description configuration form is to give an easy-to-use UI for site builders to override the component descriptions. The form can also be used to control what components can be passed as context to the agent (Should it use only SDCs, SDCs and blocks, or SDCs, Blocks, and code components?). For example, disabling Blocks from here would be a better idea if you don't want the agent to use blocks in generating templates or building page sections. This would help to reduce the context as well.
Watch this video to see template generation in action with the Starshot demo design system theme.
Wrapping up
What makes Canvas AI interesting is how it’s been woven into Drupal’s existing logic. Each agent plays a clear role, translating prompts into structured actions instead of loose suggestions. Together, they show how a content management system can evolve without changing what makes it reliable.
The design of Canvas AI feels deliberate. The separation between agents, the orchestration layer, and the reliance on component metadata all point toward a system that values control and transparency as much as convenience. It’s a reminder that progress in CMS design doesn’t always come from adding new interfaces but from finding better ways for tools to work together.