## Summary Custom flows will be able to use AI Catalog agents as sub-agents through an `include` section in the flow YAML. This issue covers what Rails does **when the flow is saved**: accept the new YAML, check every referenced agent, and record the link. Running the flow is #628315. Part of gitlab-org&23526. The YAML shape is the one DWS reads in [`reference.py`](https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/blob/main/duo_workflow_service/agent_platform/v1/catalog/sources/reference.py): ```yaml include: - source: ai-catalog item_type: agent item_id: "123" version: "1.2.0" components: - name: coordinator type: AgentComponent prompt_id: coordinator subagents: - source: ai-catalog item_type: agent item_id: "123" version: "1.2.0" ``` ## Scope ### 1. Accept the YAML In !257686. - [x] Add a top-level `include` array to [`flow_v2.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/4555df2fa543/app/validators/json_schemas/ai_catalog/flow_v2.json). The file has `additionalProperties: false` at the top level, so `include` is currently rejected. - [x] Each `include` entry has `source` (enum, `ai-catalog` only for now), `item_type` (enum, `agent` only), `item_id` (string of digits) and `version` (string matching `^\d+\.\d+\.\d+$`, required). `item_id` has to be a string. DWS reads it as a string and does not convert a YAML integer, so `item_id: 123` fails there with a type error. - [x] Change the [`subagents` items](https://gitlab.com/gitlab-org/gitlab/-/blob/4555df2fa543/app/validators/json_schemas/ai_catalog/flow_v2.json#L294-L306) from `{name}` only to `oneOf` `{name}` or the same reference shape. DWS decides an entry is a reference when it has a `source` key ([`looks_like_ref`](https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/blob/main/duo_workflow_service/agent_platform/v1/catalog/sources/reference.py#L27-L38)). - [x] Save the YAML exactly as written. `yaml_definition` already stores the raw text. - [x] Put the new behaviour behind a feature flag. The schema file is static JSON, so the flag check goes in the services: when the flag is off and the definition has `include`, return an error. A `subagents` reference has to match an `include` entry field for field. DWS checks this in [`_resolve_claim`](https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/blob/main/duo_workflow_service/agent_platform/v1/catalog/binding.py#L89-L137) during the save call, so Rails does not repeat it. ### 2. Check each reference Mostly in !258326. One class turns an `include` entry into an item, a version and an agent definition, or an error. Both save services and #628315 use it. - [ ] Load the item and the pinned version. A missing item, a missing version, or an item that is not an agent is a user error (!258326). - [ ] Visibility: a private agent only from a flow in the same project. A restricted agent only from a flow in the same top-level group The agent must be at least as visible as the flow (!258326, !259407). - [ ] Permission: the user saving the flow needs `read_ai_catalog_item` on each agent (!258326). - [ ] ~~MCP servers: each of the agent's servers has to exist, and the user needs `read_ai_catalog_mcp_server`.~~ Moved to #632032 with the MCP tools themselves. The sub-agent runs with built-in tools only in iteration 1. - [ ] Limit: at most 20 agents per flow (!256851). - [ ] Size: all agents together must fit in 112 KiB, the limit for one run (!256851). - [ ] Run the checks in both save services, before the DWS call. Any failure blocks the save (!258326). The agent does not need to be enabled in the flow's project. Agents cannot reference other agents. ### 3. Record the dependency - [x] Add the `dependency_version_id` column (!256807). - [x] Remove the unused `FlowHelper#populate_dependencies` (!256807). - [ ] Write one row per `include` entry on the new flow version, with the pinned version (!258326). - [ ] A new released version gets new rows. Editing a draft version replaces its rows (!258326). ## Save errors UX direction from `@michaelmoyers` in [this comment](https://gitlab.com/gitlab-org/gitlab/-/work_items/627641#note_3811287822). - Every failed check above blocks the save. - Errors show in the form as a list of strings. Errors about the YAML shape include the line. Errors about a reference name the item. - When the version does not exist, list the item's versions. - Wrap every new string in `s_('AICatalog|...')`. ## Documentation Ship the docs in the same MR as the code. Write `subagents` with no hyphen. - [`custom_flows_schema.md`](https://gitlab.com/gitlab-org/gitlab/-/blob/4555df2fa543/doc/user/duo_agent_platform/flows/custom_flows_schema.md#L106): add an `include` section with the YAML above, the exact-version rule, the limit, the visibility rules, and the allowed `source` values. - [`custom.md`](https://gitlab.com/gitlab-org/gitlab/-/blob/4555df2fa543/doc/user/duo_agent_platform/flows/custom.md#L119-L122): remove the note that a custom flow cannot call a custom agent. Explain how to find an agent's item ID and version. - [`claude-edit-v1-flow-registry.md`](https://gitlab.com/gitlab-org/gitlab/-/blob/4555df2fa543/doc/user/duo_agent_platform/flows/claude-edit-v1-flow-registry.md#L190): add the reference shape to the `subagents` row. - [`agents/custom.md`](https://gitlab.com/gitlab-org/gitlab/-/blob/4555df2fa543/doc/user/duo_agent_platform/agents/custom.md#L243): add "In a custom flow" under "Use an agent". - [`ai_catalog.md`](https://gitlab.com/gitlab-org/gitlab/-/blob/4555df2fa543/doc/user/duo_agent_platform/ai_catalog.md#L191): say the visibility rules also apply when a flow references an agent. - Feature flag: add a history entry and a flag note ([guide](https://gitlab.com/gitlab-org/gitlab/-/blob/b46ed43f3151a50f92b6f43175657a00ac07d90d/doc/development/documentation/feature_flags.md)). ## Duo CLI No CLI change in this issue. Two things to know: - `duo run --flow-config <path>` ([option](https://gitlab.com/gitlab-org/editor-extensions/gitlab-lsp/-/blob/main/packages/cli/src/backend_option_defs.ts)) starts a flow from a local YAML file. That path never reaches the checks in this issue. DWS is the only validation there. - The CLI cannot send catalog agents yet. That work is in [gitlab-lsp#3082](https://gitlab.com/gitlab-org/editor-extensions/gitlab-lsp/-/issues/3082). ## MRs 1. Schema and feature flag: !257686 2. Limits: !256851 3. Resolver, save checks and dependency rows: !258326 4. Documentation: !259499 ## Out of scope - Run time and the Rails-to-DWS contract (#628315, ai-assist#2870). - What happens when a run-time permission check fails. Open Question 5 in gitlab-org&23526. - "Uses" / "used by" UI and newer-version notices (#628318). - Visibility changes on already-referenced agents (#616785). - MCP servers as direct `include` entries. - MCP tools and the MCP server check for referenced agents (#632032). - Loose pinning like `v1.2.*`. ## Blockers - !258326 needs !257686 and !256851 to merge first. ## Related - DWS: ai-assist#2833 (save), ai-assist#2870 (run) - Discussion on #627641: [permissions](https://gitlab.com/gitlab-org/gitlab/-/work_items/627641#note_3785717552), [schema](https://gitlab.com/gitlab-org/gitlab/-/work_items/627641#note_3786585128), [save vs run time](https://gitlab.com/gitlab-org/gitlab/-/work_items/627641#note_3802794670)