# \[META\] Move AI Agents architecture into the AI module **Type:** Meta / Plan **Target project:** `project/ai` (AI module) **Version:** 2.0.x > Status: Draft — not yet pushed to GitLab. When filed, this is the parent/meta issue and each item below becomes a related child issue. ## Problem/Motivation The agent abstraction currently lives entirely in the contrib `ai_agents` module. The agent entity, the execution loop (`AiAgentEntityWrapper::determineSolvability()`), the control mechanisms (tool description rewriting, forced tool usage, return-directly, forced property values), the event system and the concrete content/field/taxonomy function calls are all bundled together. This couples the _concept_ of an agent and its _runtime_ to one module, makes the runner impossible to swap, and prevents other modules (or external systems such as Symfony AI) from acting as agent runtimes. For the AI module 2.0 release we want to lift the **structure** of an agent into the AI module, define a **swappable agent runner** abstraction with a shared **event** and **control-plugin** system, ship two concrete runners (a native Drupal runner and a Symfony AI runner), and move `ai_agents`' bespoke function calls onto the AI module's Tool API and out into a dedicated contrib module. ## Goal - Agent entity, input/output definitions and system prompt defined in the AI module. - Agent runner as a swappable plugin; runtime no longer hardwired. - A shared event system and a control-mechanism plugin system used by _all_ runners. - Two runners shipped: Drupal and Symfony AI. - Function calls migrated to the Tool API and out of `ai_agents`. - Migration path so existing agents become AI-module Drupal agents. ## Child issues (relations) | \# | Issue | Relation | |----|-------|----------| | #3586524 | \[Discuss\] Define the canonical agent definition | part of this meta | | #3586501 | Structured input definitions for agents (Tool API input) | part of this meta | | #3586502 | Structured output definitions for agents (Tool API output) | part of this meta | | #3586503 | Switch agents to the Tool API + extract function calls to contrib | part of this meta | | #3586504 | Move the agent entity structure into the AI module | part of this meta; blocks #3586501, #3586502, #3586505 | | #3586505 | Agent runner abstraction as plugins | part of this meta; blocks #3586506, #3586507 | | #3586506 | Drupal agent runner | part of this meta; blocked by #3586505 | | #3586507 | Symfony AI agent runner | part of this meta; blocked by #3586505 | | #3586508 | Runners support running tools under a configured role/permissions | part of this meta; relates to ai_agents#3518167 | | #3586509 | Shared runner event points | part of this meta; blocked by #3586505 | | #3586510 | Control-mechanism plugin system for runners | part of this meta; blocked by #3586505, #3586509 | | #3586511 | Migration scripts: existing agents → Drupal agents | part of this meta; blocked by #3586504 | | #3586512 | Integrate runner with Symfony Messenger (or similar) | part of this meta; blocked by #3586505 | ## Suggested sequencing 1. **#3586504** (entity in AI module) — foundation for everything. 2. **#3586501 / #3586502** (structured input/output on the entity). 3. **#3586505** (runner abstraction) → then **#3586509** (events) and **#3586510** (control plugins). 4. **#3586506 / #3586507** (concrete runners) consuming #3586509 and #3586510; **#3586508** layered on the runners. 5. **#3586503** (Tool API switch + contrib extraction) — can proceed in parallel after #3586504. 6. **#3586511** (migration) once #3586504 lands; **#3586512** (Messenger) once #3586505 lands. ## Already started work that is current * #3553408+ * #3553398+ * #3573899+ * #3560619+ * #3560792+ ## Remaining tasks - [ ] File child issues against `project/ai` and link them to this meta. - [ ] Confirm the new contrib module name for the extracted function calls (see #3586503). - [ ] Confirm 2.0 deprecation policy for `ai_agents` after the move.