## Summary Add an `ai_agent` config entity to `canvas_dev_ai` that builds a page by placing one component row per hop, and wire the four placement tools that currently ship inert. Part of https://git.drupalcode.org/project/canvas/-/work_items/3591777. ## Current behavior `canvas_dev_ai` runs one agent per chat turn as a client-side hop loop, and only `canvas_component_agent` is wired to it — so the dev flow can build JS code components but cannot build a page. `canvas_ai:place_components`, `canvas_ai:edit_components`, `canvas_ai:set_page_value` and `canvas_ai:get_component_details` are all registered, kernel-covered, and listed by no agent. ## What this agent is Canvas AI currently has four agents involved in building a page: `canvas_page_builder_agent`, which places one or a group of components; `canvas_template_builder_agent`, which builds a full page from scratch; `canvas_title_generation_agent`, which sets the page title; and `canvas_metadata_generation_agent`, which sets the page's meta description. The dev page builder agent added in this issue is meant to replace all four with a single agent. As of this issue, its capabilities are: creating a full page, placing one or more components, editing props on existing components, and setting the page title and meta description. Once this design is proven out, the live `canvas_page_builder_agent`, `canvas_template_builder_agent`, `canvas_title_generation_agent` and `canvas_metadata_generation_agent` will be deleted and this agent renamed to `canvas_page_builder_agent` — that consolidation is out of scope for this issue. ## What this agent should do - **Create a full page** using the components available in the catalog. - **Place new components** at specific locations — above, below, or inside a given component. If the user has selected a component in the page, they can refer to it as "it", "this", or "here" instead of naming it explicitly. - **Edit existing components.** E.g. the user selects a CTA on the page and asks the agent to make the text punchier or change the button label. - **Edit components in bulk by matching content or props**, not just selection. E.g. "make all testimonials positive" (a tone instruction applied across every testimonial component's copy), or — if a component has a `theme` prop controlling its color — "make all of that component 'light theme'". - **Generate the page title and description.** The agent reads the current layout, which carries the page's content, so it can generate a title/description grounded in that context without the user re-explaining what the page is about. The user can also ask it to make the title and description SEO-friendly, and the agent updates them accordingly. **Ideal environment to develop this agent against:** Drupal CMS 2 with the Byte theme or a starter template, since either ships with a large number of SDC components to place and edit against. ## Tools Action tools this agent calls: - **`canvas_ai:place_components`** — places one or more components onto the page. ([3591811](https://git.drupalcode.org/project/canvas/-/work_items/3591811)) - **`canvas_ai:edit_components`** — updates the props of components already on the page, addressed by UUID. ([3591812](https://git.drupalcode.org/project/canvas/-/work_items/3591812)) - **`canvas_ai:get_component_details`** — given a list of component IDs, returns each component's description, props, and slots, so the agent can fetch full metadata only for the candidates it shortlisted from the catalog. ([3591814](https://git.drupalcode.org/project/canvas/-/work_items/3591814)) - **`canvas_ai:set_page_value`** — sets the title or meta description of the current `canvas_page`. ([3591813](https://git.drupalcode.org/project/canvas/-/work_items/3591813)) `default_information_tools` — injected automatically, not called by the agent's own decision: - **`canvas_ai:get_component_context`** — with `catalog_only: true` and `available_on_loop: [1]`, returns the lean id/name/description catalog of every available component; injected once on the first hop only and persists in chat history. (`catalog_only` parameter: [3591920](https://git.drupalcode.org/project/canvas/-/work_items/3591920)) - **`canvas_ai:get_current_layout`** — returns the current page layout from the tempstore; injected on every hop so the agent always reasons from the latest tree. (Pre-existing `canvas_ai` tool, predates this roadmap — no tracked issue.) ## Important notes - This agent must be developed and tested against `canvas_dev_ai`'s `CanvasDevAiBuilder`, not the live `canvas_ai` module's `CanvasBuilder`. `CanvasDevAiBuilder::render()` calls `setLooped(FALSE)` — the client-side hop loop this agent is designed for. `CanvasBuilder` still loops server-side. See the roadmap meta-issue: https://git.drupalcode.org/project/canvas/-/work_items/3591777. - **To enable dev mode:** install the `canvas_dev_ai` module. With it installed, the chat UI loads from `AiWizardDev.tsx` instead of the live `AiWizard.tsx`. - **Every hop** must send the updated current layout back to the controller. - **When `canvas_dev_ai` is not installed**, the chat UI must not load the dev agent or its tools — the live flow and its agents/tools must be unaffected. ## References An initial implementation, along with a demo, exists in the POC: - **File:** https://git.drupalcode.org/project/canvas/-/blob/412f16bda2d41ad2f56e49cda2a152446846ca2/modules/canvas_ai/config/install/ai_agents.ai_agent.canvas_page_builder_agent.yml - **MR:** https://git.drupalcode.org/project/canvas/-/merge_requests/1214 - **Video:** https://git.drupalcode.org/project/canvas/-/work_items/3591615#note_1079176 That POC prompt carries extensive instructions on how to use the `place_components` tool and how to structure its YAML input. All of that can be dropped — `place_components` now has a well-defined typed schema (https://git.drupalcode.org/project/canvas/-/work_items/3591881). The same applies to `edit_components` and `set_page_value`: both already ship with a well-defined schema (https://git.drupalcode.org/project/canvas/-/work_items/3591812, https://git.drupalcode.org/project/canvas/-/work_items/3591813), so no input-shape instructions are needed for them either. Pass the `[canvas_ai:selected_component]` and `[canvas_ai:available_regions]` tokens to the agent. Component deletion or rearrangement (e.g. moving a component to the top/bottom, React-style) is already covered by the existing **Out of scope** section below. ## Design criteria - **The prompt must be extensible.** If a new tool is added later (e.g. a future `move_components` tool), it should be addable without restructuring the whole prompt. ## Prop setting guideline changes The existing agents' prop setting logic (https://git.drupalcode.org/project/canvas/-/blob/1.x/modules/canvas_ai/config/install/ai_agents.ai_agent.canvas_page_builder_agent.yml?ref_type=heads#L81) needs the following changes: - **Link/URL props:** drop the rule forcing `https://example.com` as the default. Instead: use the component's default value if one is available; otherwise fall back to `https://example.com`. - **Image props:** relax the "copy the exact default object" rule. - If the user supplies a media ID, set the prop directly to that ID (e.g. `banner_image: 3`). - If the user gives no value, use the exact default values from the image prop, as before. - **Empty slots:** remove the "empty slots are forbidden" rule. Empty slots are allowed — don't state this explicitly either way; let the agent decide. ## Tool call restriction Enable **"Restrict multiple calls"** for the `place_components` tool in the agent's tool settings, so the model cannot call it more than once in a single response. Set the **"Multiple call error message"** to: *"This tool can only be called once to place multiple components at multiple places, provide different operation lists."* Set `max_loops` to 50. ## Module versions Create the `ai_agent` config entity against `drupal/ai_agents` **1.3** and `drupal/ai` **1.4**. The `ai_agent` entity's prompt field uses an MDX editor that has issues rendering YAML and tokens correctly — the prompt may not display properly in the agent edit UI. This is an upstream issue, not something to work around here. ## Tests - Kernel: one two-hop placement turn end to end, in the style of `modules/canvas_ai/tests/src/Kernel/Agents/CanvasComponentAgentEndToEndTest.php` — hop 1 decides, hop 2 runs `place_components` and the response carries `operations`. - Kernel: installing `canvas_dev_ai` creates the agent, every ID in `tools` and `default_information_tools` resolves to a registered `AiFunctionCall` plugin, and the config passes schema validation. - Vitest: `receiveMessage()` resolves only after the operations handler has finished. ## Out of scope - Removing or relocating components — no `DeleteComponents` / `MoveComponents` tool exists, so this agent places and edits only. - Reading the selected agent from the request (https://git.drupalcode.org/project/canvas/-/work_items/3591919). - The broader kernel coverage matrix for this agent. **Depends on** https://git.drupalcode.org/project/canvas/-/work_items/3591920 for the `catalog_only` parameter. _Issue generated with AI assistance._