>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3591627. --> Reported by: [tim bozeman](https://www.drupal.org/user/2241356) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>The entity_blueprint_ai tool naming is inconsistent and the tool set includes responsibilities that belong elsewhere:</p> <ul> <li><strong>Naming inconsistency.</strong> Tools use mixed patterns: <code>get_blueprint_summary</code>, <code>get_blueprint_component</code>, <code>update_component</code>, <code>add_component</code>. The verb-object pairing is unclear and the <code>get_blueprint_*</code> prefix is redundant noise in the tool namespace.</li> <li><strong>Overlapping update tools.</strong> <code>update_component</code> and <code>update_fields</code> both modify entity data but with different scopes and signatures. The AI must choose between them and understand the internal distinction between "component" and "fields" &mdash; a leaky abstraction.</li> <li><strong>generate_image doesn't belong here.</strong> Image generation is a provider-specific feature (Imagen via Provider). It was placed here because it needed entity context, but the deferred operation system now provides a clean way for field handlers to signal async work without a dedicated tool.</li> <li><strong>switch_workspace doesn't belong here.</strong> Workspace switching is a general site operation, not an entity_blueprint concern. It should be a standalone ai_agents tool.</li> <li><strong>No event system for tool actions.</strong> Modules like ai_plus need to react when AI tools persist entities (e.g. to queue page refresh commands) but have no clean hook point. They must subscribe to generic ai_agents events and reverse-engineer what happened.</li> <li><strong>Shipped agent config is fragile.</strong> The optional config <code>ai_agents.ai_agent.page_builder.yml</code> ships a system prompt and tool list that immediately becomes stale as tools are renamed or added. Agent configuration should be managed per-project.</li> </ul> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <h4>Tool renames (clear verb-noun pattern)</h4> <ul> <li><code>get_blueprint_summary</code> / <code>get_blueprint</code> &rarr; <code>ReadEntity</code> (summary and full modes via parameter)</li> <li><code>get_blueprint_component</code> &rarr; <code>ReadElement</code></li> <li><code>get_blueprint_schema</code> &rarr; <code>ReadSchema</code></li> <li><code>update_component</code> / <code>update_fields</code> &rarr; <code>UpdateElement</code> (unified flat-property update)</li> <li><code>add_component</code> &rarr; <code>AddElement</code></li> <li><code>remove_component</code> &rarr; <code>RemoveElement</code></li> </ul> <h4>Removed tools</h4> <ul> <li><code>GenerateImage</code> &mdash; replaced by ai_plus's deferred operation processor and image generation field handler</li> <li><code>SwitchWorkspace</code> &mdash; moved to a standalone ai_agents tool outside this module</li> <li><code>GetBlueprint</code> &mdash; merged into <code>ReadEntity</code> as the "full" mode</li> </ul> <h4>AiToolActionEvent</h4> <p>New Symfony event dispatched by tool plugins after notable actions (e.g. <code>entity_persisted</code>). Context includes the entity, targets (which components/fields changed), and deferred operations. Subscribers (like ai_plus) react to tool actions without coupling to specific tool implementations.</p> <h4>EntityBlueprintToolBase expansion</h4> <ul> <li>Backend resolution via <code>BlueprintBackendResolver</code> &mdash; tools no longer hardcode content entity assumptions</li> <li>Event dispatching &mdash; base class fires <code>AiToolActionEvent</code> after persistence</li> <li>Result formatting as YAML for readable LLM output</li> <li>Target tracking propagated from <code>BlueprintResult</code></li> <li>Workspace requirement messaging updated to reference new standalone workspace tools</li> </ul> <h4>Other changes</h4> <ul> <li>Removed shipped <code>ai_agents.ai_agent.page_builder.yml</code> optional config</li> <li>Added <code>EntityBlueprintAiFormHooks</code> for workspace-related form alters</li> <li><code>AiLogCommands</code>: truncates base64-encoded binary data in log output to keep <code>drush ai:tail</code> readable</li> </ul> <h3 id="summary-api-changes">API changes</h3> <p><strong>Tool plugin IDs changed</strong> (affects agent configs referencing old IDs):</p> <table> <tr> <th>Old ID</th> <th>New ID</th> </tr> <tr> <td><code>entity_blueprint:get_blueprint_summary</code></td> <td><code>entity_blueprint:read_entity</code></td> </tr> <tr> <td><code>entity_blueprint:get_blueprint</code></td> <td>(merged into read_entity)</td> </tr> <tr> <td><code>entity_blueprint:get_blueprint_component</code></td> <td><code>entity_blueprint:read_element</code></td> </tr> <tr> <td><code>entity_blueprint:get_blueprint_schema</code></td> <td><code>entity_blueprint:read_schema</code></td> </tr> <tr> <td><code>entity_blueprint:update_component</code></td> <td><code>entity_blueprint:update_element</code></td> </tr> <tr> <td><code>entity_blueprint:update_fields</code></td> <td>(merged into update_element)</td> </tr> <tr> <td><code>entity_blueprint:add_component</code></td> <td><code>entity_blueprint:add_element</code></td> </tr> <tr> <td><code>entity_blueprint:remove_component</code></td> <td><code>entity_blueprint:remove_element</code></td> </tr> <tr> <td><code>entity_blueprint:generate_image</code></td> <td>(removed)</td> </tr> <tr> <td><code>entity_blueprint:switch_workspace</code></td> <td>(removed)</td> </tr> </table> <p><strong>New event:</strong> <code>Drupal\entity_blueprint_ai\Event\AiToolActionEvent</code> &mdash; dispatched on tool actions. Subscribe with a standard Symfony event subscriber.</p> <p><strong>Removed optional config:</strong> <code>ai_agents.ai_agent.page_builder.yml</code> &mdash; existing sites must remove or update their agent configuration manually.</p>